Documentation maintenance

index.rst is the single Sphinx entry point. Keep the existing guides in source/ and place subsystem detail under the topic that owns it:

source/
  getting_started.md, tutorials.md, gallery.md   learning
  dsl.md, resources.md                           established programming guides
  tile/                                         Tile programming guide
    design.md, execution.md, layouts.md          overview and formal model
    values.md, memory.md, pipeline.md            operations and effects
    staging.md, kernels.md                      capture/JIT surface and examples
  internals/                                    compiler and Runtime implementation
    tile/                                       TileIR, export, Runtime and target plans
  performance/                                  measured results and validation
    tile/                                       current status, route results, checkpoints

  • Introduce Tile from the existing DSL and architecture guides. Do not add each new Tile report or experiment as a peer of those guides in the root toctree.

  • Keep a current status page short and answer-first. Put chronological updates in performance/tile/checkpoints.md, detailed measurements in the route or reduction reports, and raw runs in scripts/benchmark/tile_torch/results/.

  • Distinguish proposed language contracts, implemented lowering, executed correctness tests and performance claims. Retain negative results and the original device/dtype/shape/timing/allocation/math-policy qualifications.

  • Keep historical schedule tables and test-run counts with performance and validation evidence. Implementation references describe invariants and link to those records; they should not accumulate a second experiment diary.

  • Give a long reference a single responsibility before adding another section. Tile syntax belongs in source/tile/; IR mutation/capture algorithms and bridge realization belong in source/internals/tile/. The generic planner, backend policy API, Metal matrix family, Metal reductions and TIRx CPU plans have separate owners. Cross-link them instead of extending a monolithic language or planner document.

  • Label pseudocode and proposed extensions at their reading entry point. Keep the historical design checklist in the architecture decisions; it is not the current implementation plan or evidence of completion.

  • Give long references a local contents list. After splitting a document, replace inherited cross-page chapter numbers with descriptive links, while preserving the published section anchors.

  • Put diagrams in _static/<topic>/. Use relative MyST figure and literalinclude directives; use download for repository evidence outside the documentation tree.

  • The canonical Tile example is source/tile/tile_programming_poc.cpp. Both CMake and XMake compile it through the capture tests; do not fork a prose-only copy when changing its syntax.

  • Every reader page belongs in one owning toctree. Cross-link other reading paths without giving the same page multiple parents. custom_agility_sdk.md belongs to getting started; coroutine extensions belong to implementation.

  • Preserve published URLs when moving pages. _ext/legacy_urls.py and the redirect template generate legacy HTML routes without duplicate Markdown pages. SPLIT_FRAGMENTS preserves old section links when a landing page remains in use; the shared layout redirects only those moved fragments. Every old section must still exist or resolve to its new owner.

Install Doxygen first (brew install doxygen on macOS; the Linux docs CI uses sudo apt-get install -y doxygen). Doxygen parses the C++ declarations and comments into docs/output/xml/; Sphinx’s Breathe extension reads that index to render API Reference. It is a generated, Git-ignored artifact, not a source file to recover or commit. Regenerate it after API changes or in a fresh checkout.

Build from the repository root:

doxygen docs/Doxyfile
uv run --no-project --python 3.13 --with sphinx --with sphinx-rtd-theme \
  --with myst-parser --with breathe sphinx-build -b html -W --keep-going \
  docs docs/_build/html
uv run --no-project --python 3.13 --with sphinx \
  python scripts/check_docs.py docs/_build/html

Doxygen is required for the generated API reference (docs/output/xml). A machine without it can preview the handwritten pages, but that preview does not pass the complete documentation build: do not suppress missing-XML warnings and report it as full API-reference validation.

Use a fresh output directory for publication checks; an incremental build can retain obsolete HTML from deleted source files. Check rendered navigation, diagrams, tables, example inclusions and old-URL redirects, not just the build exit code. Generated _build/ content is not committed.

The Sphinx extension rejects missing or multiple owning toctrees. scripts/check_docs.py checks local links, assets and published compatibility anchors (including split references) in generated HTML. It does not check remote links or substitute for visual review and the Doxygen/API build. Run it on the same fresh output tree you intend to publish.