Building the docs

The site in docs/ is built with Astro and Starlight. It has three kinds of pages:

• Hand-written pages in docs/src/content/docs/, as Markdown or MDX.
• Tutorials, converted from the Jupyter notebooks in tutorials/ by docs/tools/notebooks.py. Each notebook is executed and its outputs (text, images, tables) are written into an MDX page.
• API reference, generated from the docstrings by starlight-pydocs, one page per module.

Requirements

• Node 22 or newer.
• The package installed with the docs extra: pip install -e ".[docs]".

Commands

make docs-install     # npm packages and the Python docs extra
make docs-notebooks   # execute tutorials/*.ipynb and convert them to pages
make docs-dev         # live preview at http://localhost:4321/template-python/
make docs-build       # the static site in docs/dist, as in CI
make docs-preview     # serve docs/dist
make docs-clean       # remove generated pages and build output

make docs-notebooks only reruns a notebook whose cells changed since the last run; pass FORCE=1 to rerun all of them.

Writing tutorials

Put a notebook in tutorials/. Its first # Heading becomes the page title and the first paragraph its description. Cell tags control the output:

Tag	Effect
remove-cell	the cell is left out of the page
hide-input	the code is hidden, the outputs are kept
remove-output	the outputs are left out
raises-exception	an error output is shown, not a failure

Math in $...$ and $$...$$ is rendered with KaTeX.