Glossary

Terms used throughout this documentation, defined once here. Where a term carries nuance, this entry is the place that carries it: other pages use :term: and let the definition live in one location.

base URL: The URL the deploy tree is published under. HTML in deploy/html/ links its peers relatively and does not depend on it; output outside that tree — PDFs above all — has it baked in at build time.
builder: A Sphinx output format a document is built in — html, latex. A document declares the builders it supports; each one gets its own build target and its own folder in the deploy tree.
consumer: A project that uses zdocs to build its documentation. Everything a consumer supplies enters through the ZDOCS_* variables, the registry, or its own document sources.
controlled document: A document carrying a formal header — owner, classification, approval dates, version — and a transition history, managed with the docctl tool. See Command-line tools.
deploy tree: The build’s published output, organised by builder: deploy/<builder>/<document>/. Publishing a set is a directory sync of deploy/html/. See The deploy tree.
document: One unit of documentation with its own source folder, its own build target and its own entry in the registry — a manual, an API reference, a test report. A document is either built by zdocs or declared as remote; either way it is navigable and, usually, cross-referenceable.
document set: Every document declared in one registry, built together. Cross-references resolve within a set; the set is what the deploy tree contains and what is published as a unit.
doxylink: The mechanism for referencing a Doxygen-documented symbol from a Sphinx page, resolved through the target document’s tag file.
engine payload: The files zdocs hands to Sphinx and Doxygen when it runs them — configuration, extensions, templates, theme. Split by tool into sphinx/ and doxygen/, distinct from doc/, which is zdocs’ own documentation.
group: A named section of the navigation sidebar. Every document belongs to exactly one, and groups are declared in the registry alongside the documents.
intersphinx: Sphinx’s mechanism for resolving references into another Sphinx document’s objects.inv. zdocs derives one mapping entry per peer from the registry.
kind: What sort of document a registry entry describes, and therefore how it is built and cross-referenced: sphinx, doxygen, or one of the three remote kinds that produce no local build.
need: A sphinx-needs object: a requirement, a specification, a test case, a result — anything typed, identified and linkable. Needs are exported per document and imported by peers, which is how traceability spans a set.
need type: The name of a class of need. These names belong to the consuming project’s methodology, not to zdocs: the engine works in roles and resolves each to the project’s own name. See 0009. Need types and links are a consumer-supplied role→name mapping.
objects.inv: Sphinx’s machine-readable index of everything a document defines. Any Sphinx site publishes one, which is what makes both local peers and remote sites cross-referenceable.
prefix: A document’s cross-reference namespace, unique within a set. Sphinx peers reference it as :external+<prefix>:; Doxygen symbols are reached through a role of the same name.
registry: documents.yaml: the single file declaring a document set. Build targets, cross-reference wiring and navigation are all derived from it, and it is the only place a document is declared. See The registry schema.
stage one: The first of the two build passes. Produces only cross-reference indexes — an objects.inv per Sphinx document, a tag file per Doxygen document — and publishes nothing. Cross-document references are expected to be unresolvable here.
stage two: The second build pass. Rebuilds every document with the complete set of indexes available and produces the published output. A warning here means something real; a warning in stage one usually does not.
tag file: Doxygen’s equivalent of objects.inv. zdocs names every tag file it generates doxygen.tag; a remote site’s may be called anything, and is declared explicitly.
twister: Zephyr’s test runner. Its output directory is an input to the test-report directives; a build with no results present renders a “not found” node rather than failing.
ztest: Zephyr’s C test framework. Annotated ztest sources are the origin of the whole test-documentation chain — see From annotated C to a test report.