add doc generation workflow

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+# Update the API documentation whenever the `main` branch changes.
+# This documentation lives in its own `docs` branch.
+name: docs
+
+on:
+  push:
+    branches:
+      - 'test-master'
+
+jobs:
+  update-docs-branch:
+    runs-on: ubuntu-22.04 # latest
+    permissions:
+      contents: write # allow push
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: true
+
+      - name: Update docs branch
+        run: |
+          sudo apt-get install -y doxygen
+          ./make-docs.py
+
+      - name: Commit
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add --force docs/
+          git commit --message="update docs"
+
+      - name: Push to docs branch
+        uses: ad-m/[email protected]
+        with:
+          github_token: ${{ github.token }}
+          branch: docs
+          # Force push so that `docs` branch always looks like `main`,
+          # but with 1 additional "update docs" commit.
+          # This seems simpler than trying to cleanly merge `main` into
+          # `docs` each time.
+          force: true

.gitignore

@@ -486,3 +486,5 @@ cmake-build-debug/
 certs/*.key
 certs/*.pem
 certs/*.crt
+
+/docs

doxygen/doxygen.conf

@@ -7,8 +7,8 @@ GENERATE_LATEX   = NO
 IMAGE_PATH = doxygen/image/
 
 # Output in the build directory
-OUTPUT_DIRECTORY = 
-INPUT = /var/lib/jenkins/workspace/ReleaseToProd/release/../.
+OUTPUT_DIRECTORY = docs/
+INPUT=./
 
 # Scan only the source files that we wish to make part of the public API
 EXCLUDE_PATTERNS += */.git/*

doxygen/make-docs.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+import os
+import shutil
+
+if shutil.which('doxygen') is None:
+    exit("You must install doxygen")
+
+# clean
+if os.path.exists('docs'):
+    shutil.rmtree('docs')
+
+# build
+if os.system('doxygen doxygen/doxygen.config') != 0:
+    exit(1)