Build the documentation locally

Run these commands from the repository root with uv installed.

Preview changes

uv run --group docs inv docs

Open http://localhost:12346. The server rebuilds the documentation when source files change. Press Ctrl+C in the terminal to stop it.

The docs dependency group includes Sphinx, notebook conversion tools, and pypandoc-binary, which bundles the Pandoc executable. The Sphinx configuration uses the bundled executable if pandoc is absent from PATH.

Installing the Python package named pandoc alone does not install that executable and will not resolve a PandocMissing error. Install the docs dependency group using the command above instead. A system installation of Pandoc on PATH also works.

Update release notes

Add the target version and user-visible changes to docs/explanation/changelog.md before publishing a package release. The release pipeline updates version metadata; it does not generate release notes. Record API server improvements in a separately dated table entry because they are deployed independently of the Python package.

Check the build before publishing

uv run --group docs sphinx-build -b html -W -E -a \
    -d build/doctrees docs build/docs
uv run python scripts/public_docs.py check build/docs

The first command treats Sphinx warnings as build failures. The second checks the generated site for restricted content and build artifacts. Keep the doctrees directory outside the HTML output directory.

Documentation builds render saved notebook cells and outputs without executing them. They do not authenticate to the API or submit data queries. Validate notebook code separately when changing an example.