docs: redirect GitHub Pages docs to GitBook

.github/workflows/pages-redirect.yml

@@ -0,0 +1,79 @@
+name: GitHub Pages Redirects
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'scripts/publish_docs.py'
+      - 'scripts/validate_docs.py'
+      - 'scripts/generate_github_pages_redirects.py'
+      - 'tests/docs/**'
+      - '.github/workflows/pages-redirect.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'scripts/publish_docs.py'
+      - 'scripts/validate_docs.py'
+      - 'scripts/generate_github_pages_redirects.py'
+      - 'tests/docs/**'
+      - '.github/workflows/pages-redirect.yml'
+  workflow_dispatch:
+
+jobs:
+  redirect-site:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run redirect generator tests
+        run: python -m unittest discover -s tests/docs -p 'test_*.py'
+
+      - name: Build GitBook site
+        run: python scripts/publish_docs.py
+
+      - name: Validate site output
+        run: python scripts/validate_docs.py
+
+      - name: Build GitHub Pages redirects
+        run: python scripts/generate_github_pages_redirects.py
+
+      - name: Upload generated redirect site as PR artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages-redirect-preview
+          path: gh-pages-redirect/
+
+      - name: Deploy to gh-pages branch
+        if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+          mv gh-pages-redirect/ /tmp/gh-pages-redirect/
+
+          git fetch origin gh-pages || true
+          if git rev-parse --verify origin/gh-pages >/dev/null 2>&1; then
+            git checkout gh-pages
+          else
+            git checkout --orphan gh-pages
+            git rm -rf .
+          fi
+
+          rsync -a --delete --exclude='.git' /tmp/gh-pages-redirect/ .
+          git add -A
+          if ! git diff --cached --quiet; then
+            git commit -m "docs: update GitHub Pages redirects from ${{ github.sha }}"
+            git push origin gh-pages
+          fi

.gitignore

@@ -22,4 +22,5 @@ __init__.py
 uv.lock
 
 # docs build output (pushed to gitbook-docs branch by CI)
-/site
+/site
+/gh-pages-redirect