fix: enforces Sphinx build warnings and controlled deployment

Configures the docs CI workflow to:
- Make Sphinx builds fail on warnings (`-W`).
- Block Pull Request merges if docs build fails.
- Deploy docs to GitHub Pages only from the `main` branch.

Author: panyamkeerthana

.github/workflows/sphinx-deploy.yml

@@ -1,18 +1,50 @@
-name: Deploy Sphinx documentation to Pages
+name: Build & 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 documentation 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 documentation 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

docs/best-practices.md

@@ -2,7 +2,7 @@
 
 This page provides information on how to get the most out of Granite.Code. It covers best practices for getting accurate and helpful chat responses, as well as supplementary options which make Granite.Code's features even more powerful.
 
-Before you read this guide, you should be familiar with the main Granite.Code features, which are described in the [getting started tutorial](FIXME).
+Before you read this guide, you should be familiar with the main Granite.Code features, which are described in the [getting started tutorial](https://docs.granitecode.github.io/getting-started).
 
 ## Asking effective questions