Consolidate docs deployment workflows

.github/workflows/docs-build.yml

@@ -0,0 +1,42 @@
+name: Build and Upload Docs
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  contents: read      # needed for checkout
+  pages: write        # to deploy to GitHub Pages
+  id-token: write     # to authenticate with GitHub Pages
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: docs-build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install system deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+          python3 -m pip install --upgrade pip
+          python3 -m pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Build docs (MkDocs + Doxygen)
+        run: |
+          make clean document
+          touch site/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site

.github/workflows/publish-docs.yml → .github/workflows/docs-publish.yml

@@ -1,22 +1,21 @@
-name: Docs production build and deploy
+name: Publish Docs
 
 on:
   push:
     branches: [ master ]
-  pull_request:
-    branches: [ master ]
 
 permissions:
-  contents: read      # needed for checkout
-  pages: write        # to deploy to GitHub Pages
-  id-token: write     # to authenticate with GitHub Pages
+  contents: read
+  pages: write
+  id-token: write
 
 concurrency:
-  group: "pages"
+  group: "pages-prod"
   cancel-in-progress: true
 
 jobs:
   build:
+    name: docs-build
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -40,8 +39,7 @@ jobs:
           path: site
 
   deploy:
-    # Only deploy on push to master, NOT on pull_request
-    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    name: deploy-pages
     needs: build
     environment:
       name: github-pages