How these docs are built

This documentation is built as engineering, with the same rigor as the code it describes. This page explains how, because how a system is documented is itself a signal of how it is built.

Documentation held to a passing bar

The site is built with Sphinx and the Furo theme, from reStructuredText sources under docs/source/. It is compiled and deployed to GitHub Pages by a GitHub Actions workflow on every push to main.

The build runs with warnings treated as errors:

sphinx-build -b html -W --keep-going docs/source docs/_build/html

The -W flag is the point. A broken cross-reference, a malformed heading, or a link to a page that no longer exists does not produce a quiet warning that rots over time; it fails the build, exactly like a failing test. The documentation passes or it does not ship. This is what keeps a docs site honest as the code underneath it changes.

Reference that cannot drift

The API reference is generated directly from the source with Sphinx autodoc. It reads the actual classes, signatures, and docstrings out of the installed package rather than restating them by hand. Hand-copied API docs drift from the code the moment the code changes; generated ones cannot, because the code is their only source.

Prose grounded in the code

The technology chapters are not generic tutorials. Each was written against the specific module that uses the library in question, and describes how it is actually used here, not how it is used in the abstract. The same discipline applies to the concept chapters: where the tool has a known limit, the docs state it plainly rather than imply a capability the code does not have. The Schema Adaptation chapter documents its own classification edge cases; the Privacy and Data Access chapter names the guarantees it does not make. Documentation that hides limits is documentation that cannot be trusted on the claims it does make.

Structure

The site is organized by what a reader is trying to do, not by how the code is packaged:

  • Getting Started gets a reader from nothing to generated data.

  • Concepts explains the design decisions and why they were made.

  • Foundations covers the principles and the project’s lineage.

  • Technology Stack justifies each dependency in the context of the system.

  • Reference is the exhaustive, lookup-oriented material (CLI, API, testing).

Diagrams are authored as text (Mermaid) and rendered in-page, so they live in version control alongside the prose and change with it.

Why this matters

Treating documentation as a versioned, reviewed, CI-gated part of the project, rather than an afterthought, is a deliberate practice. It is the difference between a README that describes what the software was intended to do on the day it was written, and a documentation system that is held accountable to what the software actually does today.