This document explains how to generate, browse, and maintain the project's API reference, which is produced by Doxygen from the in-tree source comments. The configuration file is the top-level Doxyfile; the wrapper script is scripts/builders/docs.sh; the canonical entry point is just docs::build.

Generating the HTML

From the repository root:

just docs::build                              # build into build/docs/html/
just docs::build && open build/docs/html/index.html      # macOS
just docs::build && xdg-open build/docs/html/index.html  # Linux

just docs::build is a thin wrapper around bash scripts/builders/docs.sh, which in turn:

Resolves the project-pinned doxygen release via scripts/builders/provision_doxygen.sh. On first use the official release binary is downloaded (sha256-verified) into build/tools/; later runs reuse that copy offline. A doxygen already on PATH is only used when it matches the pin exactly.
Detects whether dot (Graphviz) is also available. When dot is missing the script overrides HAVE_DOT=NO so the build still succeeds, just without include/directory graphs.
Runs the pinned doxygen over Doxyfile, with PROJECT_NUMBER expanded from the top-level VERSION file. Output lands in build/docs/html/; warnings are appended to build/docs/doxygen-warnings.log.

Why the doxygen version is pinned

docs/doxygen_theme/header.html is a doxygen HTML template: it was generated by doxygen -w html from exactly the pinned release, then extended with the theme's script includes. Doxygen substitutes only the $placeholders it knows; rendering the template with any other version leaves the unknown ones (e.g. $mermaidjs) as literal text on every published page and mangles the <head>. The vendored doxygen-awesome theme likewise supports a bounded range of doxygen releases. Building with the distro or Homebrew doxygen of the day is therefore not supported – always go through just docs::build / scripts/builders/docs.sh, which enforce the pin.

Theme (doxygen-awesome)

The site uses the MIT-licensed doxygen-awesome-css theme in its sidebar-only variant with the dark-mode toggle, fragment copy button, and paragraph links extensions. The theme files are vendored as a unit under docs/doxygen_theme/ – never hand-edit individual lines. To update the theme:

Replace each vendored doxygen-awesome*.css / *.js file and LICENSE with the same-named file from the chosen upstream release tag.
Check the release's supported doxygen range; move the pin in scripts/builders/provision_doxygen.sh if required (the version, the tag, and every artifact sha256 beside it).
Regenerate docs/doxygen_theme/header.html: run doxygen -w html header.html footer.html style.css Doxyfile with the pinned binary, then re-add the theme's <script> includes and the DoxygenAwesome*.init() block at the end of <head> (see the theme's "Extensions" documentation). Discard the generated footer.html/style.css – the project uses the defaults.
Rebuild with just docs::build and confirm no literal $placeholders appear in build/docs/html/index.html.

To open the freshly-built HTML in a browser without a separate command, pass --open:

bash scripts/builders/docs.sh --open

What gets indexed

Doxyfile's INPUT block is the authority. It covers the README.md (rendered as the main page via USE_MDFILE_AS_MAINPAGE), the Markdown under docs/, and all first-party source: the libraries, the adapters onto the vendored stacks, the co-processor firmware, the products and the examples, and the developer tooling, host emulator included.

libs/third_party/ and apps/shared_libs/third_party/ are explicitly excluded – vendored SOUP is documented under docs/SOUP/ instead, not via Doxygen. So is docs/doxygen_theme/ (the vendored HTML theme itself).

The repository is private while the docs site is public, so GitHub Actions status badges in Markdown would render as broken images for site visitors. scripts/gen/doxygen_md_filter.py (wired via FILTER_PATTERNS) strips them from every Markdown page at docs-build time; they remain in the files on github.com.

How to read the generated HTML

After just docs::build, navigate to build/docs/html/index.html. The left-hand sidebar carries the rendered README, a page per source file (its @file block, its declared symbols, and – if Graphviz is on PATH – include and caller graphs), an alphabetical symbol index, and a type index. Two settings shape what appears there: EXTRACT_ALL = YES surfaces even file-static helpers, while EXTRACT_PRIVATE = NO keeps NSC-private and priv_* helpers hidden by default.

Each function page renders the Doxygen tags the block carries. @brief, @details, @param[in/out], @return / @retval, two @pre, two @post, @note and @since are required and gated (see the Workflow section below for by what). @warning, @see and @par MC/DC: also render, and are conventions rather than requirements – see docs/STYLE_GUIDE.md "Function documentation" for the measurement behind that split. Cross-references resolve to other pages automatically.

Workflow

When you add a new function, struct, enum, or file:

Write the full Doxygen header per the CLAUDE.md rules. Several gates hold that, and none of them is the clang-tidy recipe – clang-tidy has no Doxygen tag checking of any kind, and this line used to name it. scripts/checks/doxy_audit.py covers the required tag set on every function, a doc comment on every enum value / struct member / macro, and the file-header and @param-direction style; scripts/checks/check_doc_attachment.py covers the harder question of whether a block actually describes the symbol it is attached to. They run in the pre-commit-checks / doc-attachment CI gates and in scripts/git/pre-commit.
Run just docs::build locally and confirm the new symbol appears in the rendered HTML.
Tail build/docs/doxygen-warnings.log for any new warnings triggered by your change. The repository goal is zero new warnings (the standing tag-coverage baseline is reported in docs/DOXYGEN_GAPS.md).
Open build/docs/html/index.html in a browser and verify the page renders, links resolve, and any @code ... @endcode examples are syntax-highlighted.

Configuration knobs

Everything is in Doxyfile, and the three settings worth knowing about are EXTRACT_PRIVATE (off, so priv_* helpers stay hidden), HAVE_DOT (on, but the wrapper turns it off when Graphviz is absent rather than failing), and the call-graph node ceiling, which trades build time for larger graphs. A brand-new top-level library needs a line in INPUT; nothing else discovers it.

Common issues

"Found end of C comment inside a backtick block" – a Markdown code fence in a Doxygen comment was opened with ` but never closed before the comment terminator. Audit the offending file and balance the backticks.
"the name 'examples/ek_ra8d2/hw_validated/hil/blink/src/main.c' supplied as the argument in the \\file statement is not an input file" – the @file <path> in the file header does not match the file's on-disk location. Update the @file line.
"unable to resolve reference to ..." – you cited a symbol via \see or \ref but Doxygen could not find it. Either fix the spelling or document the missing target.

Continuous integration

The docs are built in CI through scripts/builders/docs.sh and the same pinned doxygen, twice, for different reasons:

.github/workflows/docs-publish.yml – on every push to main (and manual dispatch), runs just docs::build and force-publishes build/docs/html/ to the orphan gh-pages branch via scripts/builders/publish_docs.sh.
The Doxygen warnings job in .github/workflows/firmware.yml – runs bash scripts/builders/docs.sh --gate (separate build/docs-gate/ output tree, private members extracted, no graphs) and fails on non-benign warnings.

The recommended local workflow is still to run just docs::build before pushing any change that touches public API surface.