Docs pipeline

This repo treats docs as a built product rather than a pile of independently refreshed generated files. The stable contract is: one blocking docs CI workflow validates committed docs state, builds the site artifact when required, and deploys that exact validated artifact on main; explicit refresh workflows are the only write-mode generators for tracked docs assets.

Source versus generated

Asset family	Source of truth	Regenerated by	Stored in git	Blocks PRs
README.md	README.template.md plus examples/ snippets	python scripts/render_readme.py	Yes	Yes, via sync check
docs/performance.md	benchmarks/artifacts/* plus scripts/templates/performance.md.template	python scripts/render_performance_page.py	Yes	Yes, via sync check
docs/assets/diagrams/*	docs/assets/diagrams/src/*	python scripts/render_d2_diagrams.py	Yes	Yes, via check-only drift validation
docs/assets/generated/*	code and benchmark sources under src/, scripts/, and benchmarks/artifacts/	python scripts/build_visual_artifacts.py all --profile ci	Yes	Yes, via check-only drift validation and targeted browser suites
benchmarks/artifacts/*	benchmark tests plus pricing/numerics source inputs	python scripts/build_benchmark_artifacts.py	Yes	Freshness check only when benchmark or performance inputs change
built docs site	docs/, mkdocs.yml, generated assets, package API docs	python -m mkdocs build --strict	No	Yes

Workflow contract

docs-ci

This is the authoritative blocking docs workflow on pull requests.

• installs the pinned docs/test environment from scripts/ci-constraints.txt
• checks README.md and docs/performance.md synchronization
• checks benchmark snapshot freshness only when benchmark or performance inputs changed
• validates D2 diagrams in check-only mode
• builds the MkDocs site once, uploads the built-site artifact, and reuses that artifact for downstream browser audits and Pages deploy
• runs blocking Playwright smoke and DOM audits against the prebuilt site artifact
• runs targeted accessibility checks on curated impacted paths
• keeps the blocking gate focused on deterministic sync/build/smoke checks instead of full-page snapshot drift

docs-assets-refresh

This is the manual regeneration path for tracked docs artifacts.

• refreshes README, diagrams, generated visual assets, and the rendered performance page
• refreshes authoritative Playwright snapshots after visual asset, diagram, or performance-page updates so the write-mode refresh path does not leave blocking baselines stale
• validates the regenerated site with strict MkDocs
• is the primary write-mode path for tracked docs assets
• opens a draft PR when there is something to review

benchmarks

This is the authoritative benchmark refresh path.

• reruns the benchmark suite
• rebuilds benchmarks/artifacts/*
• rerenders docs/performance.md
• uploads raw and derived benchmark evidence
• opens a draft PR with refreshed benchmark outputs

Deployment in docs-ci

Deployment lives inside docs-ci rather than in a separate cross-run workflow.

• it only runs on push to main
• it only runs when docs_site_required == true
• it stages and deploys the same built-site artifact that passed blocking validation earlier in the workflow
• it verifies curated live public docs routes after deploy with python scripts/docs_site_contract.py verify-public

docs-advisory

This workflow is scheduled or manually triggered for the heavier audits.

• generated visual asset drift checks
• external link checks
• DOM/CSS audits beyond the blocking smoke set
• broader accessibility passes
• full Ubuntu-authoritative snapshot verification
• Windows browser checks
• check-only validation for generated docs assets and full-page visual drift that is informative but too noisy for the blocking gate

Local contributor contract

• Install the default hooks with pre-commit install --hook-type pre-commit --hook-type pre-push; the pre-commit hook refreshes benchmarks/artifacts/benchmark_source_manifest.json automatically when benchmark-sensitive sources change.
• Use python scripts/docs_doctor.py or python scripts/pre_push_docs_validation.py --mode fast for the same portable pre-push checks that run locally by default.
• Use python scripts/render_readme.py and python scripts/render_performance_page.py when updating generated text artifacts intentionally.
• Use python scripts/run_ci_visual_regression.py build-assets when the authoritative Ubuntu visual-asset refresh matters more than native Windows rendering.
• Use python scripts/pre_push_docs_validation.py --mode manual if you want local Playwright and Docker-backed checks before pushing.
• Use the benchmarks workflow instead of manually editing benchmarks/artifacts/*.

Failure layers

Docs failures are grouped by layer so the next action is obvious:

• environment setup
• generated text sync
• benchmark snapshot freshness
• generated visual asset build or integrity
• strict MkDocs build
• browser smoke, DOM, accessibility, or docs-impact-selected authoritative visual checks
• advisory-only audit failures