Documentation pipeline updated

.github/workflows/build-and-publish-doc.yml

@@ -1,33 +1,69 @@
-name: Build and Deploy Docs
+name: Sphinx Docs
 
 on:
-  push:
-    branches: 
-      - main
   pull_request:
     branches:
       - main
-  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
-  build-and-deploy-docs:
+  build-docs:
+    name: Build Sphinx Documentation
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          fetch-depth: 0
+          python-version: "3.11"
 
-      - name: Install sphinx
-        run: pip install sphinx==8.2.3 sphinx-rtd-theme==3.0.2
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx==8.2.3 sphinx-rtd-theme==3.0.2
 
-      - name: Build Sphinx HTML
-        run: sphinx-build -b html ./source ./build
+      - name: Build HTML docs
         working-directory: ./docs
+        run: make html
 
-      - name: Deploy documentation to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html
+          name: html-docs
+          path: ./docs/build/html
+
+  publish-docs:
+    name: Publish Documentation to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build-docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: html-docs
+          path: ./docs/build/html
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4