raptor.conformance.doc_includes

raptor.conformance.doc_includes — reusable Sphinx include/literalinclude target checker.

Why this exists. eagle/docs/conf.py sets suppress_warnings = […, “docutils”, …] – the category Sphinx uses for “Include file … not found” – so a broken literalinclude target prints one warning line and the build still exits 0. Several of eagle’s targets once pointed at a directory later extracted to a downstream package, and this shipped silently for the length of the pass. Blanket -W is not an option (most surfaced eagle warnings are pre-existing doxygen duplicate-ID noise under the SAME “docutils” category, so the suppression cannot be narrowed without also un-suppressing that noise). This module is a targeted, non-Sphinx-warning-dependent check instead: a plain filesystem scan that reproduces Sphinx’s own path-resolution rules and asserts every include/literalinclude target exists.

Why it lives here, not downstream: the logic was always path-free (it takes docs_root as an argument and knows nothing about which repos exist on disk or where they live), but it once shipped from a downstream sibling’s own suite. That placement broke silently the day that sibling’s own suite shape changed (a sibling-free venv-gate leg could no longer resolve the tool at all, landing the file blocked-at-collection instead of running). The claim “eagle’s includes resolve” is eagle’s; a claim gated only in a downstream sibling’s suite stops running the day that suite changes shape. Moving the LOGIC here (raptor ships to every consumer; include = [“raptor*”]) lets each owner (eagle/python/tests/test_doc_includes.py, a downstream package’s own test) certify its OWN docs tree directly, with raptor keeping zero sibling/repo knowledge.

Resolution rules (reproduce Sphinx’s `include`/`literalinclude` directives exactly – verified against the live eagle tree, not assumed):

1. a target starting with “/” is relative to the docs SOURCE directory (docs_root, the directory conf.py lives in) – never the filesystem root (a target like /schemas/manifest-v1.schema.json resolves to <docs_root>/schemas/manifest-v1.schema.json, not /schemas/… on disk);

2. otherwise the target is relative to the directory containing the document that names it (the common case);

3. _build/ is excluded – it holds generated copies of the same source pages (_build/html/_sources/**), so scanning it double-counts every hit and would also flag the generated tree’s own copies once a source fix has already landed but the stale _build/ has not been rebuilt.

Handles both reStructuredText directives (.. literalinclude:: target, eagle’s dialect) and MyST fenced directives (a code fence whose info string is {literalinclude} target – three backticks followed by that info string, the rest of the family’s dialect) with the same scan, so the same call is reusable across the family regardless of which markup a repo’s docs use.

Module Attributes

SOURCE_SUFFIXES

Source file suffixes scanned.

Functions

main(…)	CLI entry point: print the directive count and every broken include found under each docs root given.
resolve_target(…)	Resolve an include/literalinclude target using Sphinx's own rule.
scan_docs(…)	Scan every .rst/.md file under docs_root (excluding _build/) for include/literalinclude directives, resolving each with resolve_target().

Classes

BrokenInclude	One include/literalinclude directive whose target does not exist.
DocsScanReport	One scan_docs result: the root scanned, the TOTAL number of include/literalinclude directives found (regardless of whether they resolved), and the broken subset.