Explanation

Background: how zdocs works and why it is built the way it is, for readers who want to contribute to zdocs rather than just using it.

Start with Architecture for the shape of the engine as a whole. The pages after it take one mechanism each and follow it end to end. The guidelines pages state the norms this project holds itself to, and Decisions is the historical record: every architectural decision, dated, with the situation that forced it.

• Architecture
  • Introduction and goals
  • System context
  • Solution strategy
  • Building blocks
  • Cross-cutting concepts
• The registry, and what it derives
  • One reader, two callers
  • What one entry produces
  • Opt-in by sub-block
  • Validation is a configure-time error
• The deploy tree
  • What is servable, and what is not
  • The trap this layout creates
  • Two link shapes, one tree
  • Cleaning
• Documents zdocs does not build
  • external — a link, and nothing more
  • sphinx-external — a remote Sphinx site
  • doxygen-external — a remote Doxygen site
  • The recurring hazard
  • Testing without the internet
• From annotated C to a test report
  • The chain
  • The names are the consumer’s
  • Two failure modes, deliberately different
  • Ordering
  • Parameterized tests
  • Where the test runner writes
• Engineering guidelines
  • Testing
  • Engine boundaries
  • CMake
  • Python
  • Build hygiene
• Documentation guidelines
  • Format
  • Structure
  • Two documents
  • Architecture pages
  • Facts only
  • Honesty about maturity
  • Vocabulary
  • ADRs
• Decisions
  • 0001. zdocs is a Zephyr module, included by name
  • 0002. Acceptance tests live in a consumer repository, over one cumulative fixture
  • 0003. The engine carries its own unit suite, in the engine repository
  • 0004. The registry is the single source of truth for document declarations
  • 0005. Remote documents are three kinds, not one
  • 0006. The deploy tree is organised by builder, not by document
  • 0007. Doxygen XML is engine-managed, and lives outside the servable tree
  • 0008. The Doxygen tag file is named doxygen.tag
  • 0009. Need types and links are a consumer-supplied role→name mapping
  • 0010. The engine payload is split by tool, freeing doc/ for documentation
  • 0011. Documentation structure: Diátaxis, arc42-lite, and two documents
  • 0012. Cross-document links in the HTML tree are relative