docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

# Prevent concurrent deploys from corrupting gh-pages
concurrency:
  group: docs-deploy
  cancel-in-progress: false

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

      - name: Setup uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true

      - name: Setup Python
        run: uv python install 3.12

      - name: Cache apt packages
        uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
        with:
          packages: libvtk9-dev qtbase5-dev qt5-qmake libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev
          version: 1.0

      - name: Install dependencies
        run: uv sync --group docs

      - name: Configure Git for mike
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      # One-time migration: wipe legacy gh-pages from mkdocs gh-deploy
      # so mike starts with a clean branch (safe no-op once versions.json exists)
      - name: Clean up legacy gh-pages
        if: github.event_name == 'push'
        run: |
          git fetch origin gh-pages:refs/remotes/origin/gh-pages 2>/dev/null || true
          if git show origin/gh-pages:versions.json &>/dev/null 2>&1; then
            echo "mike already initialized, skipping cleanup"
          else
            echo "First mike deploy — wiping legacy gh-pages for clean start"
            git push origin --delete gh-pages 2>/dev/null || true
          fi

      # Deploy PR preview (not shown in version selector)
      - name: Deploy PR preview
        if: >-
          github.event_name == 'pull_request' &&
          github.event.pull_request.head.repo.full_name == github.repository
        run: uv run mike deploy "pr-${{ github.event.pull_request.number }}" --push

      # Tokens for pull requests from forks are read-only. Build the docs without
      # publishing a preview so external contributions are still validated.
      - name: Build fork PR documentation
        if: >-
          github.event_name == 'pull_request' &&
          github.event.pull_request.head.repo.full_name != github.repository
        run: uv run mkdocs build

      - name: Comment PR preview link
        if: >-
          github.event_name == 'pull_request' &&
          github.event.pull_request.head.repo.full_name == github.repository
        uses: actions/github-script@v9
        with:
          script: |
            const previewUrl = `https://kmarchais.github.io/mmgpy/pr-${{ github.event.pull_request.number }}/`;
            const marker = '<!-- docs-preview -->';
            const body = `${marker}\n:book: **Docs preview**: ${previewUrl}`;

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });

            const existing = comments.find(c =>
              c.user.type === 'Bot' && c.body.includes(marker)
            );

            if (!existing) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body,
              });
            }

      # Clean up previews for closed/merged PRs
      - name: Clean up stale PR previews
        if: >-
          github.event_name == 'pull_request' &&
          github.event.pull_request.head.repo.full_name == github.repository
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git fetch origin gh-pages:refs/remotes/origin/gh-pages 2>/dev/null || true
          VERSIONS=$(git show origin/gh-pages:versions.json 2>/dev/null || echo "[]")

          echo "$VERSIONS" | python3 -c "
          import json, subprocess, sys

          versions = json.load(sys.stdin)
          for v in versions:
              name = v['version']
              if not name.startswith('pr-'):
                  continue
              pr_num = name[3:]
              result = subprocess.run(
                  ['gh', 'pr', 'view', pr_num, '--json', 'state', '--jq', '.state'],
                  capture_output=True, text=True,
              )
              state = result.stdout.strip()
              if state in ('CLOSED', 'MERGED'):
                  print(f'Deleting preview for {name} (PR is {state})')
                  subprocess.run(['uv', 'run', 'mike', 'delete', name, '--push'])
              else:
                  print(f'Keeping {name} (PR is {state})')
          "

      # "dev" always reflects the current main branch.
      # Versioned release deploys live in build-wheels.yml so they're gated on
      # a successful PyPI upload (we never publish docs for a release whose
      # wheel never shipped).
      - name: Deploy dev docs
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: uv run mike deploy dev --push