Publishing and Docs Site¶

Purpose¶

Document how the documentation site is built, validated, and published.

This page is operational, not contractual. The source of truth for behavior remains the current repository code and CI workflow.

The published site contains:

the documentation tree under docs/
the contract book under docs/book/
deep-dive pages such as architecture and CFG notes
a live sample report for the current repository build under Examples / Sample Report

The docs workflow follows this order:

Relevant files:

The sample report is generated from the current codeclone repository tree.

Generated artifacts:

The sample report is generated during docs publishing and is not committed to git. site/ remains ignored.

Build the site:

uv run --with mkdocs --with mkdocs-material mkdocs build --strict

Generate the sample report into the built site:

uv run python scripts/build_docs_example_report.py --output-dir site/examples/report/live

Then open:

Keep docs/ as the single source tree for site content.
Do not commit generated site/ artifacts.
Keep docs publishing deterministic: no timestamps in published docs paths.
Keep the sample report generated from the same commit as the site itself.
Prefer documenting docs-site mechanics here or in adjacent deep-dive pages, not inside contract chapters unless a public contract is affected.

Update this page when you change: