Update to modern GitHub Pages deployment

.github/workflows/sphinx-build.yml

@@ -1,13 +1,13 @@
-name: Update Documentation
+name: Build Documentation
 
 on:
   push:
-    branches:    
-      - main
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
@@ -19,36 +19,48 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: "3.10.12"
 
       - name: Install pipenv
         run: |
           python -m pip install --upgrade pipenv==2024.4.1 wheel
 
+      - id: cache-pipenv
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/virtualenvs
+          key: ${{ runner.os }}-pipenv-${{ hashFiles('**/Pipfile.lock') }}
+
       - name: Install dependencies
+        if: steps.cache-pipenv.outputs.cache-hit != 'true'
         run: |
           pipenv install --deploy --dev
 
-      - name: Make
+      - name: Build HTML pages
         run: |
-          pipenv run make html
-
-      # 2. Add and commit HTML files to gh-pages branch
-      - name: Commit documentation changes
+          pipenv run make html SPHINXOPTS="-W --keep-going"
+  
+      - name: Check all external links
+        id: make_linkcheck
         run: |
-          git clone https://github.com/${{ github.repository_owner }}/gui-docs.git --branch gh-pages --single-branch gh-pages
-          cd gh-pages
-          rm -rf *
-          cp -r ../docs/html/* .
-          git config --local user.email "[email protected]"
-          git config --local user.name "GitHub Action"
-          git add .
-          git commit -m "Update documentation" -a || true
-
-      # 3. Push changes to gh-pages branch (updates documentation page)
-      - name: Push changes
-        uses: ad-m/github-push-action@master
+          pipenv run make linkcheck SPHINXOPTS="-W --keep-going"
+
+      - name: Upload GitHub Pages Artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          branch: gh-pages
-          directory: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          path: docs/html/
+
+  deploy:
+    name: Deploy docs
+    runs-on: ubuntu-22.04
+    needs: build
+    if: github.event_name == 'push' && always() && !failure() && !cancelled()
+
+    permissions:
+      # Both required by actions/deploy-pages
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4