ci: fail Sphinx doc builds on warnings and deploy on successful merge to main

.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