docs.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main
    tags:
      - "v*"
  workflow_dispatch:

permissions:
  contents: write

# Serialize the entire workflow (build + deploy) to prevent race conditions.
# If two runs trigger concurrently (e.g. a push to main and a tag), the second
# queues until the first finishes. This ensures the gh-pages checkout always
# reflects the latest deployed state.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2

      - uses: extractions/setup-just@v3

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          version: "0.5.1"

      # Fetch existing site from gh-pages so previous versions are preserved.
      # The gh-pages branch is the source of truth for the deployed site.
      - name: Download existing site from gh-pages
        uses: actions/checkout@v6
        with:
          ref: gh-pages
          path: target/site
        continue-on-error: true

      # actions/checkout creates a .git/ directory inside target/site.
      # Remove it so the deploy action doesn't push git metadata.
      - name: Remove git metadata from site checkout
        run: rm -rf target/site/.git

      - name: Determine version
        id: version
        run: |
          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
            echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
          else
            echo "version=dev" >> "$GITHUB_OUTPUT"
          fi

      - name: Build versioned documentation
        run: just doc-deploy ${{ steps.version.outputs.version }}

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target/site
          publish_branch: gh-pages