From 2738f1df7bb33fc7bde55f9f81c98e36cddd0099 Mon Sep 17 00:00:00 2001
From: "Patrick M. Niedzielski" <patrick@pniedzielski.net>
Date: Wed, 30 Oct 2024 12:31:31 -0400
Subject: [PATCH] CI: Add job to build API documentation on push to `main`

Signed-off-by: Patrick M. Niedzielski <patrick@pniedzielski.net>
---
 .github/workflows/documentation.yaml | 51 ++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 .github/workflows/documentation.yaml

diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml
new file mode 100644
index 000000000..17d41eccb
--- /dev/null
+++ b/.github/workflows/documentation.yaml
@@ -0,0 +1,51 @@
+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`
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: Update docs for `main`@${{ github.sha }}
+          repository: docs