feat(ci): merge docs build and GitHub Pages deployment into ci.yml with conditional deploy

Author: Magic-Man-us

.clinerules/workflows/scaffolding-guide.md

@@ -131,3 +131,42 @@ jobs:
           path: |
             bandit-report.json
             safety-report.json
+
+  docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: write  # Needed for GitHub Pages deployment
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Sync dependencies (includes sphinx)
+        run: uv sync --all-extras --dev
+
+      - name: Build documentation
+        run: uv run sphinx-build -b html docs docs/_build/html
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html
+          keep_files: false

.github/workflows/ci.yml

@@ -81,3 +81,9 @@ python_version = "3.13"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
+
+[dependency-groups]
+dev = [
+    "sphinx>=8.2.3",
+    "sphinx-rtd-theme>=3.0.2",
+]