0010. The engine payload is split by tool, freeing doc/ for documentation

Status

Accepted.

Context

The engine shipped its Sphinx configuration, its Sphinx extensions, its templates and static files, its vendored Doxygen theme and its Doxygen header/footer all inside a folder called doc/.

Inside the engine they are not documentation at all. They are payload — the files the engine hands to Sphinx and to Doxygen when it runs them. Meanwhile the one folder an engine’s own documentation would naturally live in was occupied, and the CMake modules that drive the two toolchains (sphinx.cmake, doxygen.cmake) had no structural counterpart in the payload they configure.

Decision

Split the payload by tool, mirroring the CMake modules:

sphinx/

The shared Sphinx configuration, the extensions (including their unit suite), templates and static files.

doxygen/

The vendored Doxygen theme, header and footer, and the cross-document navigation widget.

doc/

Freed, and left deliberately empty, for the engine’s own documentation.

Consequences

  • The underscore prefixes stayed, and the nesting depth was preserved exactly. The extension test tree sits at the same depth it did before, so the fixed parents[N] indices in its configuration needed no edit. If one of those ever needs editing, a file is in the wrong place — fix the layout, not the index.

  • Only three bindings pointed into the old tree, which is what made the move cheap: two CMake variables and one hardcoded test path. Every consumer document reaches the engine’s Sphinx configuration through an environment variable and needed nothing.

  • One variable was deleted rather than updated: it was set and never read anywhere in either repository. A rename is the moment to notice that.

  • A configure does not verify this kind of change. A wrong payload path survives configure and only fails when the tool runs — and for the Doxygen half, only in the rendered output. The check that mattered was building a full sample end to end and confirming the theme files landed in the HTML.

  • The engine’s documentation, which this decision made room for, is the docset you are reading (0011. Documentation structure: Diátaxis, arc42-lite, and two documents).