CI: Add job to build API documentation on push to main

.github/workflows/documentation.yaml

@@ -0,0 +1,53 @@
+name: Generate documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-main:
+    name: Build Doxygen documentation on `main`
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Let the default GITHUB_TOKEN commit and push.
+      contents: write
+
+    steps:
+      - name: Checkout `main`
+        uses: actions/checkout@v4
+
+      - name: Clear out `docs/` subdirectory
+        run: rm -rf docs
+
+      - name: Checkout `gh-pages` into `docs/`
+        uses: actions/checkout@v4
+        with:
+          path: docs
+          ref: gh-pages
+
+      - name: Set up dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -qy doxygen
+
+      - name: Build documentation
+        # Best way to pass Doxygen config overrides on the command line is
+        # using stdin.
+        run: |
+          ( cat Doxyfile ; echo "PROJECT_NUMBER=${{ github.sha }}" ) | doxygen -
+
+      - name: Commit new API documentation to `gh-pages`
+        run: |
+          cd docs/
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+          git commit -s -am "Update C++ API docs from commit ${{ github.sha }} on main"
+          git push