ci: add pages site deployment jobs

Author: johnbartholomew

.github/workflows/doc_update.yml

@@ -18,6 +18,10 @@ jobs:
   build_website:
     name: Build website
     runs-on: "ubuntu-24.04"
+    outputs:
+      diff_status: ${{ steps.diff-generated.outputs.diff_status }}
+      artifact_id: ${{ steps.upload-pages-package.outputs.artifact_id }}
+      git_tree_hash: ${{ steps.diff-generated.outputs.git_tree_hash }}
     steps:
       - uses: actions/checkout@v6
       - name: Setup Pages
@@ -67,13 +71,62 @@ jobs:
           cd "$WORKDIR"/work
           git diff --cached --stat
           git diff --cached
+          TREE_SHA1=$(git write-tree)
+          echo "git_tree_hash=$TREE_SHA1" >> "$GITHUB_OUTPUT"
           if git diff-index --quiet HEAD; then
             echo "diff_status=clean" >> "$GITHUB_OUTPUT"
           else
             echo "diff_status=changed" >> "$GITHUB_OUTPUT"
           fi
       - name: Upload Pages package
+        id: upload-pages-package
         if: ${{ steps.diff-generated.outputs.diff_status == 'changed' }}
         uses: actions/upload-pages-artifact@v4
         with:
           path: ${{ steps.make-output-dir.outputs.doc_output_dir }}/work/
+
+  push_pages_branch:
+    name: Update gh-pages branch
+    needs: build_website
+    if: $${{ needs.build_website.outputs.diff_status == 'changed' }}
+    permissions:
+      contents: write
+    environment:
+      name: pages-via-branch-push
+    runs-on: "ubuntu-24.04"
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+          path: repo
+      - uses: actions/download-artifact@v7
+        with:
+          artifact-ids: ${{ needs.build_website.outputs.artifact_id }}
+          path: built
+      - name: Extract Artifact
+        env:
+          TREE_SHA1: ${{ needs.build_website.outputs.git_tree_hash }}
+        run: |
+          [[ ! -z "$TREE_SHA1" ]] || {
+            >&2 echo "did not get valid sha1 hash for expected git tree from builder job"
+            exit 1
+          }
+          tar -tf built/artifact.tar
+          rm --one-file-system -rv -- $(git ls-tree --name-only HEAD)
+          ls -R
+
+  publish_pages:
+    name: Direct publish pages
+    needs: build_website
+    if: $${{ false && needs.build_website.outputs.diff_status == 'changed' }}
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: "ubuntu-24.04"
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4