Skip to content

Doxygen Site

Note

This page covers Doxygen (C/C++). For Sphinx-based Python documentation, see Sphinx Site.

The framework integrates a Doxygen HTML site alongside the hand-written KB artifacts (cards, math docs). The Doxygen site provides auto-generated, always-up-to-date structural data that is expensive to maintain by hand.

Why Both Cards and Doxygen?

Artifact Provides Maintained by
KB Card Why — design rationale, algorithm, failure modes, engineering notes kb-developer (manual)
Doxygen annotations What — function purpose, parameters, return values kb-developer (manual)
Doxygen HTML site How it connects — call graphs, caller/callee trees, file dependencies, struct relationships Auto-generated from source

Cards tell you why a function exists and how the algorithm works. The Doxygen site tells you who calls it, what it calls, and how files depend on each other — relationships that change with every refactor and are impractical to track manually.

What the Doxygen Site Generates

  • Call graphs — for each function, a visual graph of what it calls
  • Caller graphs — who calls this function (reverse direction)
  • File dependency diagrams — #include relationships between files
  • Struct/type documentation — with member lists and cross-references
  • Source browser — annotated source with hyperlinked symbols
  • Search — full-text search across all documented symbols

Setup

Prerequisites

Installation

  1. Copy the Doxyfile template during framework installation:

    cp scripts/Doxyfile YOUR_PROJECT/Doxyfile

  2. Edit Doxyfile — set PROJECT_NAME, INPUT, and FILE_PATTERNS to match your project.

  3. Configure project-config.md:

    doxygen_enabled: true
doxygen_config: "Doxyfile"
doxygen_build_cmd: "doxygen Doxyfile"
doxygen_output_dir: "doc/doxygen/"
doxygen_url: ""

  4. Add to .gitignore (HTML output is generated, not committed):

    doc/doxygen/

Building

doxygen Doxyfile
# Output: doc/doxygen/html/index.html

Rebuild after any source change that affects function signatures, call graphs, or file structure.

INDEX Linking

The KB INDEX includes a Doxygen column that links each source file to its auto-generated HTML page:

| ID  | File          | Card                    | Doxygen                                        |
|-----|---------------|-------------------------|------------------------------------------------|
| S01 | src/solve.c   | [S01](cards/S01.md)     | [doxy](../doxygen/html/solve_8c.html)          |
| N02 | src/numeric.c | [N02](cards/N02.md)     | [doxy](../doxygen/html/numeric_8c.html)        |
| A03 | src/analyze.h | ---                     | [doxy](../doxygen/html/analyze_8h.html)        |

Agents looking up a card can follow the Doxygen link to see the machine-generated call graph, complementing the card's hand-written Call Graph section.

Filename Mangling

Doxygen mangles filenames for HTML output:

Source path HTML filename
src/solve.c solve_8c.html
src/io/reader.c reader_8c.html
include/types.h types_8h.html

The pattern: strip the directory, replace . with _8, append .html.

Scoring

The Doxygen quality gate (8 points max) includes:

Gate Points Pass condition
Coverage 3 Every non-static function has a Doxygen block
Parameters 2 Every param annotated with direction ([in], [out], [in,out])
Cross-refs 1 @see links include card IDs
Site generated 1 HTML output exists and is not stale
Call graphs 1 Caller/callee graphs render for documented functions

Consistency Checks

The kb-reviewer verifies:

  • INDEX Doxygen links resolve to existing HTML files
  • Card Call Graph section is consistent with the Doxygen-generated call graph
  • Doxygen site is not stale (source modified after last build → STALE)

Optional: Hosting on GitHub Pages

Projects can publish the Doxygen site alongside other documentation using a GitHub Actions workflow. A template is provided at .github/workflows/doxygen.yml.

- name: Install Doxygen
  run: sudo apt-get install -y doxygen graphviz
- name: Build Doxygen
  run: doxygen Doxyfile
- name: Deploy
  uses: actions/upload-pages-artifact@v3
  with:
    path: doc/doxygen/html