docs: Introduce a version picker on pavex.dev/docs

.github/ci_generator/templates/job_steps/build_docs.jinja

@@ -9,28 +9,22 @@
   run: |
     mkdir -p docs/api_reference
     cp -r target/doc/* docs/api_reference
-- name: Set up QEMU
-  uses: docker/setup-qemu-action@v3
-- name: Set up Docker Buildx
-  uses: docker/setup-buildx-action@v3
-- name: Build and export to Docker
-  uses: docker/build-push-action@v5
-  with:
-    context: docs/
-    load: true
-    tags: pavex-docs
+- name: Install uv
+  uses: astral-sh/setup-uv@v6
+- name: Install the project
+  run: uv sync --locked
 - name: Build docs
   run: |
-    docker run --rm -v ${PWD}:/docs pavex-docs build --strict
-- uses: actions/upload-artifact@v4
+    uv run mkdocs build --strict
+- uses: actions/upload-artifact@v5
   with:
     name: docs
     path: site/
 - name: Fix base
   run: |
     # Convert all "absolute" guide links in the reference to relative links so that we can scan for dead links
-    sudo find . -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
-    sudo find . -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
+    sudo find ./site -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
+    sudo find ./site -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
 - name: Link Checker
   uses: lycheeverse/lychee-action@v2
   with:
@@ -45,6 +39,7 @@
       --exclude-path="site/api_reference/pavex/time"
       --exclude-path="site/api_reference/help.html"
       --exclude-path="site/api_reference/settings.html"
+      --exclude-path="site/404.html"
       --exclude=".*crate#per-style$"
       --exclude="https://doc.rust-lang.org/*"
       --exclude="https://stackoverflow.com/*"

.github/ci_generator/templates/permissions.jinja

@@ -1,6 +1,3 @@
-permissions:
-  pull-requests: write
-  checks: write
 # Run if it's a PR on the official repo or a push to `main`
 if: |
   (github.event_name == 'repository_dispatch' &&
@@ -10,3 +7,6 @@ if: |
     github.event.client_payload.slash_command.args.named.sha
   )) ||
   (github.event_name == 'push' && github.event.repository.full_name == github.repository)
+permissions:
+  pull-requests: write
+  checks: write

.github/workflows/deploy_docs.yml

@@ -0,0 +1,48 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "**[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install Rust stable toolchain
+        uses: actions-rust-lang/[email protected]
+      - name: Build API reference
+        run: |
+          cargo api_ref
+      - name: Copy API reference files
+        run: |
+          mkdir -p docs/api_reference
+          cp -r target/doc/* docs/api_reference
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Install Python dependencies
+        run: uv sync --locked
+      - name: Setup git
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "[email protected]"
+          git fetch origin gh-pages:gh-pages || true
+      - name: Update unstable documentation
+        if: github.ref == 'refs/heads/main'
+        run: |
+          uv run mike deploy --push --allow-empty unstable
+      - name: Update release documentation (tag -> x.y.x)
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          TAG="${TAG#v}"
+          VERSION="${TAG%.*}.x" # Deploy `0.2.7` under `0.2.x`
+          uv run mike deploy --push --update-aliases "$VERSION" latest