Building blocks

zdocs is four areas: the CMake surface a consumer calls, the Python scripts that read the registry and check the result, the Sphinx payload handed to sphinx-build, and the Doxygen payload handed to doxygen. The split follows the tool each area serves — see 0010. The engine payload is split by tool, freeing doc/ for documentation.

Level 2 — inside zdocs

cmake/ — the consumer surface

zdocs.cmake is the entry point a consumer includes; it pulls in the rest. registry.cmake reads the manifest and creates every document’s targets, plus the per-group aggregates. sphinx.cmake and doxygen.cmake are the two document factories, each responsible for the two build stages of its toolchain. common.cmake holds shared helpers and the doc-check target. Two further modules are cmake -P wrappers invoked at build time rather than configure time — one runs Doxygen with a freshly resolved version number, the other downloads a remote peer’s tag file.

scripts/ — registry, gate, controlled documents

docrefs.py is the only reader of the registry, and every derived value — intersphinx mappings, tag file lists, navigation entries, needs imports, document manifests — comes out of it, whether the caller is CMake or a conf.py. doccheck.py is the integrity gate that runs after a full build. docctl.py is a standalone command-line tool for controlled-document transitions, and is the one part of the engine that touches no build at all.

sphinx/ — the Sphinx payload

zdocs_conf.py is what a consumer’s conf.py shim calls: it assembles the whole configuration, including the engine’s extension list, and appends the consumer’s own extensions rather than being replaced by them. The extensions divide into presentation (doc_control, qms_ref, latexinclude), build machinery (xref_builder, which provides the stage-one index builder) and the test-specification block (test_module with its Doxygen XML parser, twister reader and rST builders).

doxygen/ — the Doxygen payload

A vendored theme, the engine’s own stylesheet, and the header/footer plus cross-document navigation widget that give a Doxygen document the same sidebar its Sphinx peers have.

Where a document’s data comes from

Every consumer-supplied fact enters through one of exactly three doors: the ZDOCS_* CMake variables, the registry, or the document’s own sources. There is no fourth, and adding one is the mistake this architecture keeps having to resist — a per-document value that the registry could already derive.