docs.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'docs-requirements.txt'
      - '.github/workflows/docs.yml'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'   # release tags only, not -rc
  pull_request:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'docs-requirements.txt'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: write

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

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Configure git for mike
        if: github.event_name != 'pull_request'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Build docs (PR check)
        if: github.event_name == 'pull_request'
        run: uv run --with-requirements docs-requirements.txt mkdocs build --strict

      - name: Deploy as latest (main branch)
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases latest

      - name: Deploy release version
        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
        run: |
          # Extract minor version from tag, e.g. v2.11.2 -> v2.11
          VERSION=$(echo "${GITHUB_REF_NAME}" | sed 's/\.[0-9]*$//')
          uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases "${VERSION}" stable