Skip to content

Documentation Automation Guide

The docs automation has two responsibilities:

  • generate reference pages from schema introspection (docs/schema/*),
  • generate reusable fragments consumed by hand-written explanation pages.

These are script-driven outputs (not AI-generated text).

1) Generated Schema Navigation

Run:

uv run python scripts/generate_docs_pipeline.py

What it does:

  1. cleans previously generated schema docs,
  2. regenerates diagrams and schema pages from introspection,
  3. updates schema navigation structure in docs config,
  4. validates generated output.

Output stability: - for the same schema revision and script version, generated content is stable because class discovery and rendered lists are sorted; - updates should appear only when schema/docs sources change.

Primary script inputs:

  • scripts/verticals.py (domain/page grouping),
  • scripts/gen_docs.py, scripts/gen_diagrams.py (page + diagram generation),
  • scripts/meta_introspect.py (schema introspection).

Generated schema pages include a Related Pages section populated automatically from links already present in docs/explanation/**/*.md.

Convention:

  • if an explanation page links to schema/<vertical>.md, that explanation page is listed back on the corresponding generated schema page;
  • links are discovered by parsing markdown and resolving relative paths;
  • when no backlinks are found, no backlink section content is rendered.

For reliable results (including agent-authored docs), always include canonical links to relevant schema/*.md pages from explanation pages.

2) Generated Explanation Fragments

Run:

uv run python scripts/generate_explanation_fragments.py

This writes stable Markdown fragments to:

  • docs/snippets/generated/model_method_hierarchy.md
  • docs/snippets/generated/model_method_family_map.md

These fragments are included in hand-written pages via snippet includes and reduce manual duplication.

3) Snippet Protocol (Executable Docs)

Canonical snippet authoring rules live in Documentation Writing Guide. Marker and folder conventions are documented in docs/snippets/README.md.

Run snippet validation and execution via:

uv run python -m pytest -q tests/test_doc_snippets.py

This test module validates snippet references, syntax, and execution behavior for runnable examples discovered via # docs-snippet: runnable.

4) Ownership and Update Rules

  • If schema structure changes, regenerate schema docs.
  • If explanation inventory text changes, regenerate explanation fragments.
  • If examples change, update snippets and snippet tests in the same PR.
  • Keep generated outputs deterministic and committed with the corresponding source-script changes.

5) CI Docs Integrity Gate

GitHub Actions includes a docs-integrity job in .github/workflows/actions.yml that runs:

  1. scripts/gen_docs.py and scripts/generate_explanation_fragments.py,
  2. a diff check on generated artifacts (docs/schema, docs/snippets/generated),
  3. tests/test_doc_snippets.py,
  4. mkdocs build -q.

Use these same commands locally before opening PRs that touch documentation automation, snippets, or generated docs.