Developer Notes

Developer Notes#

How this site is built#

  • Content: Authored in Markdown via MyST; reStructuredText works too.

  • API reference: Generated by Exhale/Breathe from the Doxygen XML under docs/doxygen-xml/xml.

  • Theme: sphinx-book-theme for a clean, responsive layout with built-in sidebar TOC and search.

Adding or curating docs#

  • Put new narrative pages in docs/sphinx/ and add them to a toctree.

  • Use MyST features (admonitions, fenced code blocks, task lists) for richer docs.

  • Keep C++ API coverage focused: adjust INPUT or EXCLUDE_PATTERNS in docs/Doxyfile if you want to broaden or narrow what lands in the API tree.

Common tasks#

  • Refresh API docs after structural code changes:

    doxygen docs/Doxyfile
sphinx-build -b html docs/sphinx docs/_build/html

  • Preview a single page quickly:

    sphinx-build -b dirhtml docs/sphinx /tmp/rex-docs-preview
python -m http.server --directory /tmp/rex-docs-preview

Publish automation#

  • A GitHub Actions workflow (.github/workflows/docs-publish.yml) runs on a weekly schedule (Thu 00:00 UTC) or manually via workflow_dispatch. It builds the docs and deploys to gh-pages with CNAME rex.ouankou.com.

  • The workflow installs Doxygen, builds the XML, builds Sphinx HTML, and pushes to gh-pages. No manual steps are needed once changes land on main.

Scope#

  • Doxygen is header-only (*.h*, plus Markdown), scoped to src + README.md.

  • Private/internal members are included; undocumented/local/anon entries are skipped; heavy third-party headers (nlohmann copies) and submodules (ompparser/accparser) are excluded to keep the build manageable.