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.
• Examples, converted from the Jupyter notebooks in tutorials/ by starlight-notebooks (the section setting in docs/package.json publishes them under examples/). Each notebook is executed and its outputs (text, images, tables) are written into an MDX page.
• Example scripts, a “Scripts” group of the Examples, built from the Python scripts in examples/ by docs/tools/examples.py. Each page shows the module docstring, the complete source file, and its Matplotlib plots.

Guides, when a project has them, are hand-written pages that explain the model or a concept; anything runnable belongs in the Examples.

• API reference, generated from the docstrings by starlight-pydocs, one page per module.

The configuration (defineDocs in docs/astro.config.mjs), the look, the header, the notebook tool and the build workflow come from the shared starlight-theme of the max-models projects; change them there, and update the version in docs/package.json and .github/workflows/docs.yml to pick up a new release.

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-examples    # run examples/*.py and publish their plots
make docs-dev         # live preview at http://localhost:4321/mpifield/
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 example notebooks

Put a Jupyter notebook in tutorials/. Examples are authored only as .ipynb files. 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
fold-input	the code is in a closed “Show code” box
remove-output	the outputs are left out
raises-exception	an error output is shown, not a failure

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

Writing example scripts

Put a Python script in examples/ with a module docstring. Its first line becomes the page title and the rest becomes the description. Leave Matplotlib figures open at the end of the script so the docs builder can save them as plots. The complete script is shown on the page.