Documentation

The documentation module generates a documentation site from two sources: API reference extracted from Doxygen comments in source code, and content documentation written as Markdown files. Both are configured through a docs.xml file in the project root that follows the Diataxis framework, organizing content by audience and type.

Options

Option	Description	Default
BUILD_DOCS	Enable documentation build	OFF

The module is skipped when BUILD_DOCS is OFF, when the project is not top-level, or when no docs.xml file exists in the project root.

Prerequisites

• xsltproc — always required for processing docs.xml
• doxygen — required only when docs.xml declares an <api> element
• dot from Graphviz — optional, enables dependency graphs in API docs

Pipeline

The docs target generates documentation from two sources: API reference extracted from source code, and content documentation written as Markdown files. Both are configured through docs.xml.

API reference

Source code → Doxygen (XML) → XSLT (main.xsl) → Markdown with frontmatter

Doxygen parses the headers specified in docs.xml and produces XML output. The XSLT stylesheet transforms that XML into Markdown files with YAML frontmatter suitable for a Docusaurus documentation site. This pipeline only runs when docs.xml contains a <developer><reference><api> element.

Content documentation

docs.xml → XSLT (content.xsl) → _content.cmake → Markdown

Content documents — tutorials, how-to guides, explanations, and non-API reference — are Markdown files referenced from docs.xml. The XSLT generates a CMake script that copies them to the output directory, injecting YAML frontmatter (sidebar position, sidebar label, and title) so that the documentation site renders the navigation structure automatically.

Doxygen aliases

The following Doxygen aliases are available for marking API visibility in source documentation:

Alias	Meaning
@experimental	Experimental API, may change without notice
@internal	Internal API, not intended for external use
@private	Private API, implementation detail

These are rendered as badges in the generated documentation, helping consumers understand which parts of the API are stable.

CI behavior

When the CI environment variable is set, Doxygen warnings are treated as errors (FAIL_ON_WARNINGS). This ensures that undocumented or incorrectly documented APIs break the CI build, preventing documentation drift.

Internal links are also validated against the full portal content tree. Broken links fail the build before any release step runs.

Build targets

Target	Description
docs	Generates all documentation under ${CMAKE_BINARY_DIR}/markdown/
docs-api	Generates API reference via Doxygen + XSLT
docs-clean	Removes stale documentation output before regeneration
docs-content	Processes content documentation from docs.xml
push-docs	Deploys generated documentation to the portal repository

The push-docs target depends on docs and is only created when DOCS_DIR is configured.

Cache variables

Variable	Description	Default
BRANCH	Branch name for documentation deployment	(empty)
DOCS_DIR	Path to the documentation portal repository	(empty)

When DOCS_DIR is set, the module creates a push-docs target that deploys the generated documentation to the portal repository on the specified branch. Both variables must be set together — omitting BRANCH while setting DOCS_DIR produces a fatal configuration error.

The deployment iterates over each section/type combination (developer/reference, developer/tutorial, etc.) and invokes the portal's make push-docs for each directory that exists in the build output.

Output structure

All documentation is generated under ${CMAKE_BINARY_DIR}/markdown/, organized by audience and Diataxis type:

build/markdown/
  developer/
    reference/       # API reference and reference documents
    tutorial/        # Learning-oriented, step-by-step guides
    howto/           # Task-oriented guides
    explanation/     # Understanding-oriented background
  user/
    ...              # Same structure for end-user documentation

Usage

make docs

For deployment:

make push-docs DOCS_DIR=/path/to/portal BRANCH=component-name

docs.xml configuration

The docs.xml file in the project root defines the entire documentation structure. It follows the Diataxis framework, organizing content by audience (who reads it) and by documentation type (what kind of content it is).

Structure

<?xml version="1.0" encoding="UTF-8" ?>
<docs>
  <developer>
    <reference>...</reference>
    <tutorial>...</tutorial>
    <howto>...</howto>
    <explanation>...</explanation>
  </developer>
  <user>
    <reference>...</reference>
    <tutorial>...</tutorial>
    <howto>...</howto>
    <explanation>...</explanation>
  </user>
</docs>

Audiences

Element	Description
<developer>	Documentation for developers using the library
<user>	Documentation for end users of the application

Both are optional. Each can contain any combination of the four documentation types.

Documentation types

Each documentation type maps to a Diataxis category:

Element	Description
<explanation>	Understanding-oriented background
<howto>	Task-oriented, goal-driven guides
<reference>	Factual, structured information
<tutorial>	Learning-oriented, step-by-step guides

Top-level documentation types do not receive a sidebar position — the component does not know what siblings exist in the portal, so Docusaurus determines the order. Only sub-sections and documents within the component receive positions based on their order in docs.xml.

Section attributes

All documentation types and <section> elements share the same attributes:

Attribute	Description
category	Path to a custom _category_.json file
index	Path to a custom index.md file
title	Sidebar label (defaults to the project name)

When index is not specified, the section is deployed without a landing page — clicking the category in the sidebar expands it to show its children. When index is specified, the referenced file is copied as index.md and used as the section entry point.

Content documents

Use <document> elements to reference Markdown files:

<tutorial>
  <document path="docs/developer/tutorials/getting-started.md" />
  <document path="docs/developer/tutorials/configuration.md" />
</tutorial>

The path attribute is relative to the project root. Each Markdown file must start with a # Title line — frontmatter is injected automatically by the build system, so source files should not include it. Documents are ordered by their position in docs.xml.

Sub-sections

Use <section> elements to group documents into nested categories:

<reference title="My Project">
  <section name="modules" title="Modules">
    <document path="docs/developer/reference/core.md" />
    <document path="docs/developer/reference/utils.md" />
  </section>
  <document path="docs/developer/reference/changelog.md" />
</reference>

Attribute	Required	Description
category	No	Path to a custom _category_.json
index	No	Path to a custom index.md file
name	Yes	Directory name in the output
title	No	Sidebar label (defaults to name)

Sections can be nested arbitrarily deep. Documents and sections within the same parent are ordered by their position in docs.xml.

API reference

The <developer><reference> section can contain an <api> element to enable the Doxygen pipeline:

<reference>
  <api title="My Library API">
    <input path="include" />
    <group refid="core" />
    <page refid="error-codes" />
  </api>
</reference>

Element	Description
<api>	Declares API reference; the title attribute is required
<group>	References a Doxygen @defgroup by its identifier
<input>	Doxygen input directory, relative to the project root
<page>	References a Doxygen @page by its identifier

If no <input> elements are specified, include is used by default. Groups and pages can be nested to define the navigation hierarchy of the API documentation. The API pipeline only applies to <developer><reference>; an <api> element under <user><reference> is not processed.

When <api> is the only child of <reference> and no index attribute is set, the API reference is "collapsed" — generated files are placed directly in the reference/ directory instead of reference/api/.

Collapsing rules

The build system simplifies the output structure by collapsing sections that would otherwise create unnecessary directory nesting:

Children	Index	Behavior
0	No	Section is skipped entirely
0	Yes	Index-only section (just the index file and category metadata)
1 (document)	No	The single document is promoted to index.md
1 (api)	No	API output placed directly in the section directory (collapsed)
2+	No	Documents placed in their own directory, no landing page
1+	Yes	Documents placed in their own directory, custom index.md

Sub-sections count as children and prevent collapsing.

Full example

<?xml version="1.0" encoding="UTF-8" ?>
<docs>
  <developer>
    <reference title="My Library">
      <api title="My Library API">
        <input path="include" />
        <group refid="public-api" />
      </api>
      <section name="internals" title="Internals">
        <document path="docs/developer/reference/architecture.md" />
        <document path="docs/developer/reference/memory.md" />
      </section>
      <document path="docs/developer/reference/configuration.md" />
    </reference>
    <tutorial>
      <document path="docs/developer/tutorials/quickstart.md" />
      <document path="docs/developer/tutorials/advanced.md" />
    </tutorial>
    <howto>
      <document path="docs/developer/howto/custom-plugins.md" />
    </howto>
    <explanation>
      <document path="docs/developer/explanation/design.md" />
    </explanation>
  </developer>
</docs>