E23: Documentation site with versioned releases #246

Overview

A published API reference and narrative documentation site. The audience is
embedded engineers evaluating the library, typically in regulated industries, so
the documentation is part of the product rather than a support artifact — it is
read during procurement as a quality signal as much as a usability one.

What it delivered

The site is built with MkDocs and the Material theme, with Doxygen parsing the
public headers and the mkdoxy plugin rendering the API reference as native
Material pages. It builds locally with one command, builds in CI under
mkdocs build --strict, and deploys to GitHub Pages on every push to main.

Note for anyone reading old material on this epic: it was originally specified
as Sphinx with Breathe, and the toolchain changed during the overhaul. The
reconciliation comment below records why. Nothing in this repository uses Sphinx.

Beyond the toolchain, the epic carried the documentation set itself: the
information architecture, the compliance and porting guides, the API reference
doorways, the platform and role pages, diagrams, branding, the community-health
files, the external link checker, and a final accuracy gate over everything
written before the first public release.

What is left

Versioned publishing was reshaped and both replacement stories have landed.

• S23.05 (S23.05: stamp the version the documentation describes #251) — the site states which build it documents. Merged 2026-09-25.
• S23.06 (S23.06: signed offline documentation bundle as a release asset #252) — a signed offline bundle attached to each release. Merged
  2026-09-26. Reopened after being closed on the assumption that versioned
  publishing would cover the need.

Versioned publishing itself is deferred, with the reasoning recorded in #251
rather than here. In short: the need is real but unexercised, indexed version
directories make superseded pages findable, the site grows monotonically, and
the value falls away after 1.0.0 rather than rising to it. The bundle answers the
archival half at a fraction of the cost and is reversible; published URLs are not.

Outstanding: S23.23 (#888), the documentation accuracy audit repeated for
0.2.0. The epic closes when that does.

Out of scope

• Moving off GitHub Pages. The directory structure should stay portable, but a
  migration is not this epic's.
• Doxygen-generated dependency or call graphs.
• Growing the narrative content indefinitely. Content grows with the features it
  describes.

Constraints

The documentation must describe the library as it actually is — no dynamic
allocation, dependency injection through vtable seams, the null-object pattern,
no feature #ifdefs. Doxygen comments document contracts rather than restating
self-expressive code: ownership, lifetime, blocking behaviour, preconditions,
error semantics, thread-safety. Internal headers stay out of the public reference.

Acceptance

• Docs build locally with one command and in CI. Met.
• Public API carries contract doc-comments, rendered into the reference. Met.
• Narrative content is integrated and navigable alongside the API reference. Met.
• Every push to main updates the published site. Met.
• A reader can tell which version of the library the site documents. Met.
• A reader can obtain the documentation for the release they are using. Met.

Stories

Listed as sub-issues rather than duplicated here, so the roll-up stays honest.