ci: fail Sphinx doc builds on warnings

- Updated workflow to use `sphinx-build -W` to treat warnings as errors
- Blocks PR merges if doc build fails due to warnings
- On successful merge to `main`,rebuilds and deploys docs to GitHub Pages

 It's based on work by @jimmac

Author: panyamkeerthana

.github/workflows/sphinx-deploy.yml

@@ -2,17 +2,49 @@ name: Deploy Sphinx documentation to Pages
 
 on:
   push:
-    branches: [main] # branch to trigger deployment
+    branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
-  pages:
+  build:
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          pip install -r docs/requirements.txt
+
+      - name: Build docs with Sphinx (fail on warnings)
+        run: |
+          sphinx-build -W -b html docs/ build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
     permissions:
       pages: write
       id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-    - id: deployment
-      uses: sphinx-notes/pages@v3
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4