Documentation

This project uses Sphinx to generate documentation from docstrings (documentation in-code) and custom pages written in Markdown (through the MyST parser).

Prerequisites

The project uses:

uv for dependency management
just for task automation

Make sure you have both tools installed and a proper development environment set up (see environment.md for details).

Build documentation website

The project provides several convenient tasks for building documentation:

HTML Documentation

# Build HTML documentation
just docs-build-html

This will install the required dependencies from the docs group in pyproject.toml and build the HTML documentation to docs/_build/html/. Open docs/_build/html/index.html in a web browser to view it.

PDF Documentation

# Build PDF documentation (requires LaTeX)
just docs-build-pdf

This builds a PDF version of the documentation using LaTeX. The resulting PDF will be in docs/_build/latex/.

Write documentation using live render

For development, you can use the auto-rebuild feature:

# Start auto-building server with live reload
just docs-autobuild

Open http://localhost:8000 in a web browser to see the HTML render updated automatically when you save a documentation file.

Manual commands

If you prefer to run the commands manually instead of using just:

# Install documentation dependencies
uv sync --group docs

# Build HTML manually
uv run sphinx-build -b html -j auto -d docs/_build/cache -q docs docs/_build/html

# Auto-build with live reload manually  
uv run sphinx-autobuild -b html docs/ docs/_build --port 8000

MyST Markdown Features

Since this project uses MyST parser, you can leverage advanced Sphinx features in Markdown files, including:

Cross-references
Directives and roles
Code block highlighting
Admonitions (notes, warnings, etc.)

Refer to the MyST documentation for complete syntax reference.