Build and Coverage

The documentation should be maintained like a tested product surface, not a side artifact. This page records the local build workflow and the expected quality bar.

Local Build

Build the HTML documentation from the repository root:

uv run scripts/build_docs.py

The generated site is written to docs/_build/html.

Release Build

Build the wheel and source distribution from the repository root:

uv run scripts/build_dist.py

Alternative Direct Sphinx Build

If you need to run Sphinx directly:

uv run python -m sphinx -b html docs docs/_build/html

Coverage Expectations

The target state for docs coverage is:

  • every stable package-root export documented in the curated API pages

  • the full PinchProblem workflow documented in both guides and reference

  • every packaged sample case and notebook represented in the examples section

  • support status called out explicitly for partial or expert-only subsystems

Current Quality Gates

  • CI now runs a docs HTML build alongside the main test workflow.

  • Docs consistency checks run under pytest as part of the normal suite.