Publish the site from a gh-pages branch

.github/workflows/deploy.yml

@@ -1,4 +1,4 @@
-name: Deploy Sphinx to GitHub Pages
+name: Build and deploy documentation
 
 on:
   push:
@@ -7,17 +7,18 @@ on:
     branches: [main]
   workflow_dispatch:
 
+# contents: write lets the publish step push to the gh-pages branch;
+# pages: write lets the last step point GitHub Pages at that branch.
 permissions:
-  contents: read
+  contents: write
   pages: write
-  id-token: write
 
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  build:
+  build-docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -30,7 +31,7 @@ jobs:
         run: pip install -r requirements.txt
 
       - name: Build Sphinx
-        run: sphinx-build -W -b html docs/source _site
+        run: sphinx-build -W -b html docs/source docs/_build/html
 
       - name: Install LaTeX for PDF
         run: |
@@ -42,20 +43,40 @@ jobs:
       - name: Build PDF (pdflatex)
         run: |
           sphinx-build -M latexpdf docs/source docs/_build
-          cp docs/_build/latex/cryptnox-readers.pdf _site/cryptnox-readers.pdf
+          cp docs/_build/latex/cryptnox-readers.pdf docs/_build/html/cryptnox-readers.pdf
 
-      - uses: actions/upload-pages-artifact@v3
+      # Publish only from main or a manual run, never from a pull request build.
+      - name: Publish to the gh-pages branch
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          path: _site
-
-  deploy:
-    # Only deploy on push to main or manual trigger — not on PR builds
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          publish_branch: gh-pages
+          allow_empty_commit: false
+          keep_files: false
+          force_orphan: false
+          enable_jekyll: false
+
+      # GitHub Pages must serve the gh-pages branch, not the source branch.
+      # Set it here so the site does not depend on a manual setting; if the
+      # workflow token is not allowed to, fail with the instruction instead.
+      - name: Point GitHub Pages at the gh-pages branch
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          current=$(gh api "repos/${GITHUB_REPOSITORY}/pages" \
+                      --jq '"\(.build_type):\(.source.branch // "")"' 2>/dev/null || echo unknown)
+          echo "Pages source is currently: ${current}"
+          if [ "${current}" = "legacy:gh-pages" ]; then
+            echo "Already serving from the gh-pages branch."
+            exit 0
+          fi
+          if gh api -X PUT "repos/${GITHUB_REPOSITORY}/pages" \
+               -f build_type=legacy -f 'source[branch]=gh-pages' -f 'source[path]=/'; then
+            echo "Pages source set to the gh-pages branch."
+          else
+            echo "::error::The workflow token may not change the Pages source. A repository admin must set Settings > Pages > Source to 'Deploy from a branch', branch 'gh-pages', folder '/ (root)'."
+            exit 1
+          fi