zdocs

zdocs is a documentation engine shipped as a Zephyr module. A project declares its documents in one registry file, sets a handful of variables, and gets a build that drives Sphinx and Doxygen together, resolves cross-references between every document in the set in both directions, and produces a deploy tree that is published by copying one folder.

Warning

Pre-release. The engine is in active development and nothing is published yet: the registry schema and the ZDOCS_* contract may still change without a deprecation period. What is documented here is what the engine does today, and every page of it is built by the engine itself.

What you get for one registry entry: a two-stage build that makes circular cross-references resolve, a navigation sidebar shared by both toolchains, scoped per-document versions from your own git tags, sphinx-needs requirements traceability, test specifications rendered from annotated C, controlled-document headers, PDF output, and an integrity check that fails when a cross-reference has silently degraded to plain text.

This documentation follows the Diátaxis framework, organised into four kinds of page:

• Tutorials — guided, hands-on lessons that end with something built.

• How-to guides — step-by-step recipes for one specific task.

• Reference — precise, factual descriptions of the contract, the registry schema, the directives and the command-line tools.

• Explanation — architecture, mechanisms and the decision record, for understanding why zdocs is built the way it is.

Generated API reference — every Python module and every CMake command — lives in a companion document, zdocs API Reference, built from the sources themselves. Reference is where the two meet: it documents the surface you write against, and links into the API document for signatures.

Tutorials

• Tutorials
  • Your first document
  • Adding a Doxygen document
  • Cross-referencing two documents

How-to guides

• How-to guides
  • Building these docs
  • Adding a document to a registry-driven set
  • Publishing a deploy tree
  • Rendering test specifications from annotated source
  • Running the test suites

Reference

• Reference
  • The ZDOCS_* contract
  • The registry schema
  • Directives and roles
  • Command-line tools
  • Glossary
  • Cross-reference smoke test

Explanation

• Explanation
  • Architecture
  • The registry, and what it derives
  • The deploy tree
  • Documents zdocs does not build
  • From annotated C to a test report
  • Engineering guidelines
  • Documentation guidelines
  • Decisions