Iterating on our documentation tooling

[Atraxus]

Summary
Our current documentation is split across two tools:

• mdBook: used for high-level, conceptual documentation, published online via GitHub Pages.
• Doxygen: used for code-level documentation, built manually by developers as needed.

This issue proposes to re-evaluate our documentation tooling and structure with the goal of improving:

• Usability and accessibility of our documentation.
• Maintenance and deployment workflows.
• Developer and contributor experience.

---

Current Limitations

1. Two separate systems: Conceptual and API documentation live in different formats, places, and pipelines. This creates friction in navigation and contributes to documentation drift.
2. Non-public API docs: Doxygen output is not published or versioned, making it hard for new contributors or external users to explore internal interfaces or understand module structure.
3. Inconsistent structure: There is no unified table of contents or search across all documentation.
4. Manual build steps: Doxygen must be built locally, while mdBook is deployed online. This inconsistency increases onboarding time and documentation rot risk.
5. Styling and integration: Differing look and feel between mdBook and Doxygen makes the documentation feel fragmented.

---

Goals of This Issue

• Identify viable paths forward for improving our documentation tooling.
• Explore whether a single documentation system could better serve our needs.
• Review how other open-source projects (especially C++/systems projects) manage this.
• Consider publishability, readability, maintainability, and contributor-friendliness.

---

Possible Directions (not exhaustive)

✅ Option 1: Consolidate into Doxygen

• Move mdBook content into Markdown pages within Doxygen (via \page).
• Customize Doxygen layout with navigation/index pages.
• Automate Doxygen builds and publish to GitHub Pages via CI.
• Pros: Single tool, unified structure, no duplication.
• Cons: Limited flexibility in styling; Doxygen theming is clunky.

✅ Option 2: Consolidate into mdBook

• Minimize use of Doxygen (or remove entirely).
• Document APIs manually in mdBook or with embedded auto-generated snippets.
• Pros: Clean UX and modern styling; excellent for structured guides.
• Cons: Poor/no support for deep code documentation; hard to keep synced.

✅ Option 3: Use an integrated documentation tool (e.g., Sphinx, MkDocs, Docsify)

• Choose a Python-based or static-site tool that allows Markdown for general docs and extensions/plugins for Doxygen (e.g., breathe, exhale).
• Pros: Fully unified site, better navigation/search, wide adoption.
• Cons: Setup/migration effort; may require learning curve.

---

Action Items

Phase 1 (Discussion):

• Survey how other comparable open-source C++ or systems projects handle documentation (e.g., Godot, LLVM, [KDE], [OpenCV], [Catch2], etc.).
• Identify common patterns, tooling stacks, and pain points.
• Evaluate feasibility of each approach above.

Phase 2 (Impelementation):

• Propose and prototype a minimal, unified documentation structure.
• Add CI workflows to publish docs to GitHub Pages.