Build and maintain the documentation

Build from Python docstrings

Use Python 3.11 or newer for the documentation tooling (CI uses 3.12). The SDK itself continues to support Python 3.10. From the repository root:

python -m pip install -r docs/requirements.txt
python scripts/build_api_docs.py

Open docs/build/html/index.html in a browser. The site includes search, class/method anchors, a symbol index and links to Python source. It works locally without hosting. The build script can be invoked from another working directory; its paths are resolved relative to the repository.

The documentation uses a separate Furo layout with Python blue accents. Light, dark and system themes are available from the theme button; the choice persists across pages and reloads. Colors live in docs/source/conf.py and layout styles in docs/source/_static/studio.css. The sidebar has one application link, defined in docs/source/_templates/sidebar/brand.html.

One build command checks public docstring coverage, generates HTML with warnings treated as errors, and executes the documentation’s offline examples. To run the stages separately:

python scripts/check_api_docs.py
python -m sphinx -b html -W --keep-going docs/source docs/build/html
python -m sphinx -b doctest -W docs/source docs/build/doctest

The manual Jenkins production job checks docstring coverage, builds the HTML with warnings treated as errors, and runs the offline examples before deployment. The HTML is also retained as a build artifact. A static documentation container is built from the same committed source as the application. Caddy serves it at https://api.dimmara.com/; /api/* continues to use the authenticated API. The container has no database credentials or public ports.

Every production deployment rebuilds the reference from Python signatures and docstrings. Failed documentation checks stop deployment. No documentation is generated inside a request handler. The build also generates a Content Security Policy containing hashes of the generated inline scripts, so search and the theme switch work without allowing arbitrary inline JavaScript.

Document APIs beside their implementation

The client reference uses automodule on the package’s __all__ exports. Public methods added to those classes appear on the next build. The local engine reference explicitly selects its supported entry points. Add new local entry points to both that reference and the checker when expanding this documented API.

Write Google-style docstrings with a summary, parameter descriptions, return values and meaningful errors:

def example(model_id, *, version=None):
    """Fetch a particular saved revision.

    Args:
        model_id (str): Model UUID.
        version (int | None): Revision; None selects the latest.

    Returns:
        dict: Source and revision metadata.

    Raises:
        APIError: The revision is unavailable to this caller.
    """

The checker compares documented parameter names to actual signatures for all exported SDK classes and their own public methods. Dataclass fields belong in Attributes. Constructor arguments belong in the class docstring. Private helpers and generated dataclass methods are excluded. The same check covers the local entry points listed in the reference.

Use doctest directives for complete offline examples. Remote examples are regular code blocks because running them would create real models or jobs. Changes to signatures and defaults come directly from source; prose describing server behavior still needs review when the implementation changes.

This setup uses Sphinx autodoc and Napoleon’s Google docstring support.