Documentation was originally setup following this tutorial: Clear, Functional C++ Documentation with Sphinx + Breathe + Doxygen + CMake

breathe is used to insert Doxygen doc snippets into the Sphinx-generated documentation.

List of supported directives: https://breathe.readthedocs.io/en/latest/directives.html#directives. They have to be inserted using myst-parser directive syntax for Markdown.

Installing the necessary tools

apt install doxygen
pip install -r requirements.txt

Generating the documentation

This script will invoke doxygen & sphinx. It is design to be called from a sub-pkg fetched in deps/docs/:

deps/docs/build_docs.sh

Using Sphinx auto-reload

Once docs/conf.py has been generated by build_docs.sh:

sphinx-autobuild docs docs/_build/html --open-browser

Usage in GitHub Actions

jobs:
  doc:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4

      - name: Set up Python 3.13 🔧
        uses: actions/setup-python@v5
        with:
          python-version: 3.13

      - name: Install doxygen ⬇️
        uses: ssciwr/doxygen-install@v1
        with:
          version: "1.13.2"

      - name: Install ninja ⚙️ ⬇️
        uses: seanmiddleditch/gha-setup-ninja@master

      - name: Invoke CMake to install deps ⚙️
        run: cmake -G Ninja -S . -B build

      - name: Generate HTML documentation 🏗️
        run: deps/docs/build_docs.sh

      - name: Deploy documentation onto GitHub Pages 🚀
        if: github.ref == 'refs/heads/master'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: public/

The documentation is then published to GitHub Pages. Example: https://motis-project.github.io/utl/