System context

zdocs sits between a consuming project and the two documentation toolchains it drives. It owns no content of its own: every input comes from the consumer, and every output is a directory the consumer publishes.

Level 1 — zdocs in its environment

The consuming project

A Zephyr workspace. It supplies the document sources, one registry file describing the set, and the ZDOCS_* contract — where its repository root is, which include roots its API documentation uses, which sphinx-needs methodology applies, and where the set is published. It calls include(zdocs) and one registry function; it never reaches into engine paths. See 0001. zdocs is a Zephyr module, included by name.

The two toolchains

zdocs generates the configuration both tools run under: a conf.py shim resolves to shared Sphinx configuration, and a consumer’s Doxyfile.in is expanded and then overridden with the keys the engine owns. Neither tool is invoked directly by the consumer, and each is run twice — see Cross-cutting concepts.

Twister

Zephyr’s test runner is an input, not a dependency: its output directory is read at build time by the test-report directives, and a documentation build with no test results present renders a “not found” node rather than failing. A docs build may legitimately outrun the test run that feeds it.

The deploy tree

The single output. It is organised by builder — deploy/html/<document>/ — so publishing is a directory sync and the servable tree contains nothing that is not servable. See 0006. The deploy tree is organised by builder, not by document.

What is deliberately not in the picture: any hosting, CI or publishing machinery. zdocs produces the tree and checks its integrity; moving it anywhere is the consuming project’s business.