Building these docs

HTML is generated with Doxygen 1.18+, Graphviz, and the doxygen-awesome theme.

Once

brew install doxygen graphviz   # macOS
# or: apt install doxygen graphviz

Theme CSS/JS is vendored under docs/theme/ (doxygen-awesome v2.4.1).

Generate

From the repo root:

./docs/generate.sh

Output: docs/generated/html/index.html.

open docs/generated/html/index.html   # macOS

What the build does

1. docs/py_filter.py prepends @package / @ingroup so interp-engine/ documents as aquin.* and the public surface as aqit.
2. Doxygen parses Python docstrings (PYTHON_DOCSTRING = YES) plus the Markdown guides in docs/pages/.
3. Graphviz draws class / directory graphs (SVG).
4. Mermaid in Markdown renders in the browser.

Layout of docs/

docs/
  Doxyfile
  DoxygenLayout.xml
  groups.dox
  py_filter.py
  generate.sh
  pages/           narrative guides
  theme/           header, footer, awesome CSS/JS, extra.css
  generated/       HTML output (gitignored)

Regenerating after code changes

Docstrings on modules, classes, and functions are picked up automatically. Narrative pages are Markdown; keep @ref ids stable ({#architecture}, …).

Generated HTML is not committed. Rebuild before a docs review.