docs.yml

name: Documentation
on:
  push:
    branches:
      - develop
    tags:
      - 'v*'
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  # Job for versioned deployments (runs on develop branch and tags)
  deploy-versions:
    if: github.event_name == 'push' && (github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/v'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Important for mike to work with tags
      
      - uses: astral-sh/setup-uv@v3
        with:
          version: "0.5.*" 
          enable-cache: true
      - name: Sync
        run: | 
          uv sync --locked
          git restore uv.lock
      
      - name: Configure Git
        run: |
          git config --local user.name "GitHub Actions"
          git config --local user.email "actions@github.com"
      
      - name: Deploy docs
        run: |
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            # For tags, deploy the tagged version
            VERSION=${GITHUB_REF#refs/tags/v}
            uv run mike deploy --push $VERSION
            
            # If this is the latest version, update the 'latest' alias
            LATEST_TAG=$(git tag --sort=-creatordate | head -n 1)
            if [[ "v$VERSION" == "$LATEST_TAG" ]]; then
              uv run mike alias --push $VERSION latest
              uv run mike set-default --push latest
            fi
          else
            # For develop branch, deploy to 'dev'
            uv run mike deploy --push --update-aliases dev
          fi

  # Job for PR previews
  preview:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v3
        with:
          version: "0.5.*" 
          enable-cache: true
      - name: Sync
        run: | 
          uv sync 
          git diff
          git restore uv.lock

      # Only build and deploy if PR is opened/synchronized/reopened
      - name: Build docs
        if: github.event.action != 'closed'
        run: |
          uv run mkdocs build --site-dir site/pr-${{ github.event.pull_request.number }}

      - name: Deploy preview
        if: github.event.action != 'closed'
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          
          # Checkout gh-pages branch
          git diff
          git fetch origin gh-pages --depth=1
          git checkout gh-pages
          
          # Create preview directory if it doesn't exist
          mkdir -p pr-previews
          # Remove old preview if it exists
          rm -rf pr-previews/pr-${{ github.event.pull_request.number }}
          # Copy new preview
          cp -r site/pr-${{ github.event.pull_request.number }} pr-previews/
          
          # Commit and push
          git add pr-previews
          git commit -m "Deploy preview for PR #${{ github.event.pull_request.number }}"
          git push origin gh-pages

      - name: Comment on PR
        if: github.event.action != 'closed'
        uses: actions/github-script@v6
        with:
          script: |
            const preview_url = `https://${context.repo.owner}.github.io/${context.repo.repo}/pr-previews/pr-${context.payload.pull_request.number}/`;
            github.rest.issues.createComment({
              issue_number: context.payload.pull_request.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `📚 Documentation preview is ready!\n\nView it here: ${preview_url}`
            });

      # Cleanup preview when PR is closed
      - name: Cleanup preview
        if: github.event.action == 'closed'
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          
          # Checkout gh-pages branch
          git fetch origin gh-pages --depth=1
          git checkout gh-pages
          
          # Remove the preview directory for this PR
          rm -rf pr-previews/pr-${{ github.event.pull_request.number }}
          
          # Commit and push if there are changes
          git add pr-previews
          git diff --staged --quiet || (git commit -m "Remove preview for PR #${{ github.event.pull_request.number }}" && git push origin gh-pages)

  # Optional job to cleanup old PR previews
  cleanup-old-previews:
    if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: gh-pages
      
      - name: Get closed PRs
        id: closed-prs
        uses: actions/github-script@v6
        with:
          script: |
            const prs = await github.rest.pulls.list({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'closed'
            });
            return prs.data.map(pr => pr.number);
          result-encoding: string
      
      - name: Cleanup old previews
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          
          # Get list of preview directories
          cd pr-previews
          for preview in pr-*; do
            if [ -d "$preview" ]; then
              PR_NUM=$(echo $preview | sed 's/pr-//')
              if ! echo "${{ steps.closed-prs.outputs.result }}" | grep -q "$PR_NUM"; then
                rm -rf "$preview"
                echo "Removed old preview: $preview"
              fi
            fi
          done
          
          # Commit and push if there are changes
          git add .
          git diff --staged --quiet || (git commit -m "Cleanup old PR previews" && git push origin gh-pages)