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. - Guides, converted from the Jupyter notebooks in
guides/bystarlight-notebooks. All guide content lives in notebooks. 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.
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
Section titled “Requirements”- Node 22 or newer.
- The package installed with the
docsextra:pip install -e ".[docs]". - An MPI implementation (
mpiexec) and thempiextra, for the rank boundaries in the guides’ plots: the notebooks run on 4 ranks (DOCS_MPI_RANKS). Without them they run on one rank and the plots show a single block.
Commands
Section titled “Commands”make docs-install # npm packages and the Python docs extramake docs-notebooks # execute guides/*.ipynb and convert them to pagesmake docs-dev # live preview at http://localhost:4321/mpiarray/make docs-build # the static site in docs/dist, as in CImake docs-preview # serve docs/distmake docs-clean # remove generated pages and build outputmake docs-notebooks only reruns a notebook whose cells changed since the last run; pass
FORCE=1 to rerun all of them.
Running npm run dev, npm start or npm run build from docs/ also converts the
notebooks automatically, so the guide pages are available after a clean checkout or
make docs-clean. Conversion uses cached outputs when available; run make docs-notebooks
to execute the examples and populate those outputs. The npm commands use DOCS_PYTHON
when set, otherwise the repository’s .venv Python or the system Python.
npm run build executes changed notebooks before conversion and rejects missing, stale or
failed outputs. Plotting cells therefore produce the figures embedded in the built pages.
Development preview converts immediately from cached outputs; use make docs-notebooks
to refresh them after editing code. GPU and PETSc examples check their optional prerequisites
and explain when a hardware-dependent section cannot run.
Writing guides
Section titled “Writing guides”Put a notebook in guides/. 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 |
fold-input | code starts collapsed behind Show code, outputs stay visible |
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.