Build Documentation

Build Documentation#

1. Install the documentation dependencies#

pip install -r docs/requirements.txt

If you have issue like locale.Error: unsupported locale setting, please enter export LC_ALL=C.UTF-8; export LANG=C.UTF-8 before build the API.

2. Build the HTML site#

Local development (current version only)#

cd docs
make current-docs

Then you can preview the documentation in your browser at docs/build/html/index.html.

Multi-version docs (CI/production)#

The production docs site hosts multiple versions side by side. Each version is built independently into its own subdirectory under docs/build/html/:

docs/build/html/
├── index.html           # Redirect → latest stable
├── versions.json        # Version manifest for the sidebar selector
├── main/                # Dev docs (latest main branch)
├── v0.1.3/              # Release docs
└── v0.1.2/              # Release docs

To build a specific version into this layout:

cd docs
sphinx-build source build/html/<version>

For example, to build the main branch docs:

sphinx-build source build/html/main

Then generate the version manifest and root redirect:

python3 scripts/generate_versions_json.py --build-dir build/html

This generates both versions.json (for the sidebar version selector) and index.html (redirects to the latest stable version, falling back to main).

Old release versions beyond DOCS_MAX_VERSIONS (default: 4) are automatically pruned during CI builds.

Contents