Build the docs locally

This guide explains how to build and preview the project documentation locally using Sphinx. Makefile targets are provided so you don’t need to remember the full commands.

Prerequisites

You need uv installed. If you are using the devcontainer, everything is already set up.

Install dependencies

Install the docs dependency group:

$ uv sync --group docs

Build the documentation

Run a one-off build (warnings are treated as errors, matching CI):

$ make docs

The output is written to docs/_build/html.

Live preview

For a live-reloading server that rebuilds on changes:

$ make docs-live

Then open the URL shown in the terminal (typically http://127.0.0.1:8000).

If port 8000 is already in use, specify a different port:

$ uv run sphinx-autobuild docs docs/_build/html --port 8001