# Build the documentation locally

Run these commands from the repository root with [uv](https://docs.astral.sh/uv/)
installed.

## Preview changes

```sh
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

```sh
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.