Build and validate the documentation

The documentation is a Sphinx/MyST site using PyData Sphinx Theme, sphinx-design, and sphinx-copybutton. Read the Docs is configured by .readthedocs.yaml.

Install the toolchain

python -m pip install -e ".[docs]"

Install .[notebooks] as well when notebook execution or authoring is part of the change.

Extract tutorial figures

Executed notebooks are the source of truth for tutorial plots:

python scripts/extract_notebook_figures.py
python scripts/extract_notebook_figures.py --check

The script reads exactly the ten top-level tutorial notebooks, extracts 31 embedded PNG outputs, requires image alt metadata, and writes docs/_static/tutorials/manifest.json with source cell/output, dimensions, and SHA-256. It refuses unexpected generated PNGs instead of deleting them.

Build locally

make docs

Equivalent command:

sphinx-build -W --keep-going -b dirhtml docs docs/_build/dirhtml

-W turns warnings into failures. --keep-going reports all detectable documentation problems in one run. The dirhtml builder produces clean Read-the-Docs-style URLs.

Preview without a separate server dependency:

python -m http.server 8765 --directory docs/_build/dirhtml

Open http://127.0.0.1:8765/.

Read the Docs build

The v2 configuration uses Ubuntu 24.04, Python 3.13, the dirhtml builder, and the docs extra. Warnings fail the hosted build. Search ranking prioritizes getting-started, user-guide, tutorials, and pharmacometrics while demoting development internals.