Move docs deployment to separate job

Author: agriyakhetarpal

.github/workflows/ci.yml

@@ -254,49 +254,3 @@ jobs:
           echo -e '```\n' >> $GITHUB_STEP_SUMMARY
           (cd output/wheel && tree -a * | sed 's/^/    /' | tee -a $GITHUB_STEP_SUMMARY)
           echo -e '\n```\n' >> $GITHUB_STEP_SUMMARY
-
-  # FIXME: when ready, move this to a separate workflow or make it run on
-  # just the main branch (after a PR is merged)
-  docs:
-    needs: [style]
-    name: documentation-build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
-        with:
-          fetch-depth: 0
-          submodules: "recursive"
-      - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
-        id: setup-go
-        with:
-          go-version: "1.22.1"
-          cache: false
-          check-latest: true
-      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
-        with:
-          python-version: 3.12
-
-      - name: Restore cache for Hugo
-        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
-        with:
-          path: ./hugo_cache/
-          # This should pick up the same cache as the build_wheels job
-          key: ubuntu-latest-hugo-${{ steps.setup-go.outputs.go-version }}
-
-      - name: Install Python dependencies
-        run: pip install nox
-
-      - name: Build documentation website
-        run: nox -s docs
-
-      - name: Deploy documentation website
-        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/public/
-          publish_branch: gh-pages
-          user_name: "agriyakhetarpal"
-          user_email: "74401230+agriyakhetarpal@users.noreply.github.com"
-          keep_files: false

.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+permissions: {}
+
+jobs:
+  build:
+    name: documentation-build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          submodules: "recursive"
+
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        id: setup-go
+        with:
+          go-version: "1.26.1"
+          cache: false
+          check-latest: true
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.x"
+
+      - name: Restore Hugo builder cache
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: ./hugo_cache/
+          key: ubuntu-latest-hugo-${{ steps.setup-go.outputs.go-version }}
+
+      - name: Install Python dependencies
+        run: pip install nox
+
+      - name: Build documentation website
+        run: nox -s docs
+
+      - name: Upload documentation as artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs
+          path: docs/public/
+
+  deploy:
+    name: documentation-deploy
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+    steps:
+      - name: Download documentation artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: docs
+          path: docs/public/
+
+      - name: Deploy documentation website
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/public/
+          publish_branch: gh-pages
+          keep_files: false
+          force_orphan: true