Story: Documentation infrastructure
Table of Contents
This page documents a story in Sprint 01. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Bring up a documentation pipeline that produces a project site from the org-mode sources, integrates API documentation via Doxygen, and hosts the seed domain notes that the rest of the project will build on.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 01 |
| Now | Story closed; project site live, Doxygen integrated, domain notes seeded. |
| Waiting on | None. |
| Next | None. |
| Last touched | 2024-07-28 |
Acceptance
- A basic project site is generated and published.
- Code syntax highlighting works in the site output.
- The README serves as the site's index (no separate index file).
- A project objective is stated in the README.
- Doxygen runs over the source and the output is linked from the site.
- Initial domain notes are imported from the legacy source.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Add basic site | DONE | 2024-06-23 | 2024-06-23 | Stand up a basic project site, generated from the org-mode sources. |
| Generate Doxygen documentation and add it to the site | DONE | 2024-07-01 | 2024-07-01 | Wire Doxygen into the build and publish its output as part of the project site. |
| Copy domain notes on core concepts | DONE | 2024-06-25 | 2024-07-05 | Import the seed domain notes from the legacy source into the project's documentation tree. |
Decisions
- Org-mode as source of truth
- site is generated from the
org-mode files in
doc/. No second documentation system. - Doxygen for the API surface
- industry standard, integrates with CMake, no custom tooling required.
- README is the site index
- avoids drift between two top-level entry points.
Out of scope
- Internationalised docs.
- A separate developer manual vs. user manual (deferred — handled by generated views in v2).
See also
- How do I deploy the site? — recipe for the
deploy_siteCMake target that this story stood up. - How do I deploy the skills? — sibling pipeline for the Claude Code skill bundle.
- How do I generate PlantUML diagrams? — the diagram pipeline that later replaced the abandoned org-babel PlantUML conversion.
doc/doc.org— the top-level v1 documentation index that the basic site renders.- Compass (v2 entry point) — successor of the org-publish driven site for the new information architecture.