development.md

How to build and check the documentation locally

Start from a repository checkout with Python 3.11+, Node.js 22+, pnpm, and uv installed. Use pnpm 11.11.0 to match the CI setup used for this project.

uv venv
. .venv/bin/activate
make develop
python -m sphinx -W -b html docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html

Open http://localhost:8000/. On Windows, activate the environment with .venv\Scripts\activate.

Add a gallery example

Create a UTF-8 .mmd file in docs/src/examples/. In docs/src/examples.md, add a source listing and a rendering directive that both read it:

## Review flow

```{literalinclude} examples/review.mmd
:language: text
```

```{mermaid} examples/review.mmd
```

Use text for the source listing so it remains visible as code. A source listing with language mermaid would itself render as a second diagram.

Update the gallery's expected diagram count in js/tests/index.spec.js. The browser checks should fail if a new example produces an error instead of SVG.

Run the checks

make lint
make check-types
make test
python -m sphinx -W -b text docs docs/_build/text

make test runs Python integration tests and Chromium tests against built docs. Keep port 3000 available for the browser test server. For a docs-only edit, make lint-docs and make test-js provide the focused checks.

Rebuild the bundle with pnpm --dir js build after editing browser code or updating Pele. Before changing packaging, also run make build and make check-dist.