CI, coverage and versioned documentation¶

Versioned documentation with sphinx-multiversion¶

The HTML documentation is versioned using sphinx_multiversion.

Documentation versions are derived from Git branches, not from the package version defined in pyproject.toml and not from patch-level Git tags.

The project follows this rule:

Code is versioned using semantic versions X.Y.Z (git tags, as usual).
Documentation is versioned at the minor level X.Y.

This avoids unnecessary documentation version bumps for patch-only changes (including documentation fixes).

—

Documentation branches¶

Each supported documentation version corresponds to a dedicated Git branch:

main Represents the latest documentation.
doc/X.Y Represents the documentation for all X.Y.* releases.

For example:

main        → latest documentation
doc/0.1     → documentation for all 0.1.x releases

—

sphinx-multiversion configuration¶

The relevant configuration in conf.py is:

# Build documentation only for branches
smv_branch_whitelist = r'^(main|doc/\\d+\\.\\d+)$'

# Explicitly disable tags
smv_tag_whitelist = r"$^"

# Mark "main" as the latest version
smv_latest_version = "main"

With this setup:

Documentation is built for main and all doc/X.Y branches.
Git tags (for example v0.1.3 or v0.1.4) are ignored, but they affect SCRIPT version
Documentation fixes do not require creating new Git tags.

—

Adding or updating a documentation version¶

To add or maintain documentation for a minor release X.Y:

Create a documentation branch (once per minor version):

git checkout main
git checkout -b doc/0.1
git push origin doc/0.1

Apply documentation fixes or updates on that branch:

git checkout doc/0.1
# edit .rst files
git commit -am "Docs: update documentation for 0.1.x"

Rebuild the multi-version documentation:

uv run sphinx-multiversion docs docs/_build/multiversion

This will create version-specific directories such as:

docs/_build/multiversion/latest/
docs/_build/multiversion/0.1/

—

Building into `public/`¶

For GitLab and GitHub Pages it is convenient to build the documentation directly into the public/ directory. This is the directory that GitLab and GitHub commonly serve as the root of the project site.

Locally you can run:

uv run sphinx-multiversion docs public

This creates:

public/latest/
public/0.1/

GitLab and GitHub Pages requires a public/index.html file at the root level. Since sphinx-multiversion creates only version-specific subdirectories, a redirect file must be added.

The redirect ensures that visitors accessing the root of the GitLab and GitHub Pages site are automatically sent to the latest documentation.

—

Removing old documentation versions¶

Simply deleting a directory under docs/_build/multiversion/ or public/ is temporary. The next time sphinx_multiversion runs, it will recreate all versions for which a matching Git branch exists.

To permanently remove an old documentation version:

Delete the corresponding doc/X.Y branch:

git branch -d doc/0.0
git push origin --delete doc/0.0

Or exclude it by tightening smv_branch_whitelist.

After updating branches or configuration, rerun sphinx-multiversion to regenerate the documentation output.