ADR-012: Living Documentation

Status

Accepted

Context

Static documentation becomes stale over time:

  • Available actions in ActionRegistry change as new features are added

  • Mouse profiles in MouseDefinitions are updated with new devices

  • Screenshots may not reflect current UI state

  • Manual documentation updates are error-prone and often forgotten

We need a documentation strategy that keeps reference documentation synchronized with the actual code and data.

Decision

We will generate reference documentation from tests that introspect actual code and data.

Documentation Generation Pattern

  1. Test introspects source of truth

    • test_generate_mouse_profiles.py reads JSON files from MouseDefinitions/

    • test_generate_actions_reference.py introspects ActionRegistry

    • test_tutorial_workflow.py captures screenshots during actual workflows

  2. Test generates RST files

    • Output goes to docs/reference/_generated/ or docs/user-guide/_generated/

    • Generated files are gitignored (not committed)

    • Static RST files use .. include:: directives to pull in generated content

  3. CI runs tests → builds docs

    • GitHub Actions runs generation scripts as part of build

    • Sphinx build includes freshly generated content

    • Documentation artifacts include current generated content

What Gets Generated

Source

Generator

Output

MouseDefinitions/*.json

test_generate_mouse_profiles.py

docs/reference/_generated/mouse-profiles.rst

ActionRegistry

test_generate_actions_reference.py

docs/reference/_generated/actions.rst

UI workflow

test_tutorial_workflow.py

docs/user-guide/_generated/*.png

Generator Requirements

  • Mouse Profiles Generator: Can run standalone (Python only, reads JSON)

  • Actions Generator: Requires Slicer context (imports ActionRegistry)

  • Tutorial Generator: Requires Slicer with UI (captures screenshots)

Consequences

Positive

  • Documentation always matches current code and data

  • Tests verify documentation is generatable (catches import errors, missing data)

  • Single source of truth (code/data defines behavior AND docs)

  • No manual documentation updates for routine changes

  • CI catches documentation generation failures

Negative

  • Generated documentation must be excluded from git (requires .gitignore update)

  • Local development requires running generators to preview docs

  • Slicer-dependent generators require full Slicer environment

Neutral

  • Documentation build becomes dependent on test execution

  • Some documentation remains static (conceptual guides, tutorials prose)

  • Trade-off between flexibility (static docs) and accuracy (generated docs)

Implementation

  1. Create test_generate_mouse_profiles.py (standalone Python)

  2. Create test_generate_actions_reference.py (requires Slicer)

  3. Update docs/reference/ to include generated content

  4. Add docs/reference/_generated/ to .gitignore

  5. Update CI workflow to run generators before Sphinx build

  6. Update existing RST files to use .. include:: directives

References