documentation.yml

name: documentation


on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]
    paths:
      [docs/**, .github/workflows/documentation.yml, birdnet_analyzer/cli.py]
  push:
    branches:
      - main
    paths:
      [docs/**, .github/workflows/documentation.yml, birdnet_analyzer/cli.py]
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: "Release tag to build and publish (e.g. v2.4.0)"
        required: true
        type: string
      set_stable:
        description: "Also publish this version as stable"
        required: false
        type: boolean
        default: false
      python_version:
        description: "Python to build with (3.11 for tags pinning tensorflow 2.15)"
        required: false
        type: string
        default: "3.13"

permissions:
  contents: write

# One group per deploy target: a shared group lets a newer run evict a queued
# deploy. Overlap is safe, the deploy step retries onto a newer gh-pages tip.
concurrency:
  group: >-
    ${{ github.event_name == 'pull_request'
    && format('docs-pr-{0}', github.ref)
    || github.event_name == 'push' && 'docs-deploy-dev'
    || format('docs-deploy-{0}', github.event.release.tag_name || inputs.tag) }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Determine build source and target directory
        id: target
        env:
          EVENT: ${{ github.event_name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          RELEASE_PRERELEASE: ${{ github.event.release.prerelease }}
          INPUT_TAG: ${{ inputs.tag }}
          INPUT_STABLE: ${{ inputs.set_stable }}
        run: |
          # [[ =~ ]] anchors on the whole string, so a value containing a
          # newline cannot pass and inject extra lines into $GITHUB_OUTPUT.
          TAG_RE='^v[0-9]+(\.[0-9]+)*(-[A-Za-z0-9.]+)?$'
          case "$EVENT" in
            release)
              if ! [[ "$RELEASE_TAG" =~ $TAG_RE ]]; then
                echo "::error::release tag '$RELEASE_TAG' does not look like vX.Y.Z, not deploying docs"
                exit 1
              fi
              echo "ref=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
              echo "dest=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
              # Prereleases get their /vX.Y.Z-rc/ dir but must not become stable.
              if [ "$RELEASE_PRERELEASE" = "true" ]; then
                echo "stable=false" >> "$GITHUB_OUTPUT"
              else
                echo "stable=true" >> "$GITHUB_OUTPUT"
              fi
              ;;
            workflow_dispatch)
              if ! [[ "$INPUT_TAG" =~ $TAG_RE ]]; then
                echo "::error::tag must look like vX.Y.Z, got '$INPUT_TAG'"
                exit 1
              fi
              echo "ref=$INPUT_TAG" >> "$GITHUB_OUTPUT"
              echo "dest=$INPUT_TAG" >> "$GITHUB_OUTPUT"
              echo "stable=$INPUT_STABLE" >> "$GITHUB_OUTPUT"
              ;;
            push)
              echo "ref=" >> "$GITHUB_OUTPUT"
              echo "dest=dev" >> "$GITHUB_OUTPUT"
              echo "stable=false" >> "$GITHUB_OUTPUT"
              ;;
            *)  # pull_request: build as a check, no deploy
              echo "ref=" >> "$GITHUB_OUTPUT"
              echo "dest=" >> "$GITHUB_OUTPUT"
              echo "stable=false" >> "$GITHUB_OUTPUT"
              ;;
          esac
      - uses: actions/checkout@v7
        with:
          ref: ${{ steps.target.outputs.ref }}
      - uses: actions/setup-python@v7
        with:
          # Old tags pin dependencies that have no wheels for current Python.
          python-version: ${{ inputs.python_version || '3.13' }}
      - name: Set up uv
        uses: astral-sh/setup-uv@v10.0.1
        with:
          # Re-enabling needs a cache-suffix, or this key collides with the
          # ubuntu/3.13 test job's.
          enable-cache: false
      - name: Install dependencies
        run: uv pip install --system .[docs]
      - name: Sphinx build
        env:
          DEST: ${{ steps.target.outputs.dest }}
        run: |
          EXTRA=""
          if [ -n "$DEST" ] && [ "$DEST" != "dev" ]; then
            # Old tags hardcode a version and don't load the switcher, so both
            # are forced from here; on current conf.py the -D flags are no-ops.
            EXTRA="-D version=${DEST#v} -D release=${DEST#v}"
            EXTRA="$EXTRA -D html_js_files=https://birdnet-team.github.io/BirdNET-Analyzer/switcher.js"
          elif [ "$DEST" = "dev" ]; then
            EXTRA="-D version=dev -D release=dev"
          fi
          # Doctrees in a temp dir so they don't end up in the deployed site.
          sphinx-build -E -d "$RUNNER_TEMP/doctrees" $EXTRA docs _build
      - name: Check out site chrome from main
        if: ${{ steps.target.outputs.dest != '' }}
        uses: actions/checkout@v7
        with:
          ref: main
          path: chrome
      - name: Check out gh-pages
        if: ${{ steps.target.outputs.dest != '' }}
        uses: actions/checkout@v7
        with:
          ref: gh-pages
          path: site
      - name: Deploy to GitHub Pages
        if: ${{ steps.target.outputs.dest != '' }}
        env:
          DEST: ${{ steps.target.outputs.dest }}
          STABLE: ${{ steps.target.outputs.stable }}
        run: |
          # Guard: $DEST is interpolated into rm -rf below.
          [ -n "$DEST" ] || { echo "::error::empty deploy target"; exit 1; }

          # Re-runnable: a rejected push re-applies this onto the newer tip.
          apply() {
            # The root holds only chrome (regenerated below) and version dirs;
            # this also clears the old unversioned layout.
            find site -mindepth 1 -maxdepth 1 \
              ! -name .git ! -name 'v[0-9]*' ! -name stable ! -name dev \
              -exec rm -rf {} +
            rm -rf "site/$DEST"
            cp -a _build "site/$DEST"
            if [ "$STABLE" = "true" ]; then
              rm -rf site/stable
              cp -a _build site/stable
              # Records which release /stable/ currently holds, so later deploys
              # (which regenerate versions.json from disk) can still label it.
              echo "$DEST" > site/stable/.version
            fi
            cp -a chrome/docs/_site/. site/
            touch site/.nojekyll
            python - <<'EOF'
          import json
          import re
          from pathlib import Path

          site = Path("site")

          def sort_key(name):
              # v3.0.0 sorts above v3.0.0-rc, which sorts above v2.4.0.
              core, _, suffix = name[1:].partition("-")
              return [int(x) for x in core.split(".")], suffix == "", suffix

          versions = sorted(
              (d.name for d in site.iterdir()
               if d.is_dir()
               and re.fullmatch(r"v\d+(\.\d+)*(-[A-Za-z0-9.]+)?", d.name)),
              key=sort_key,
              reverse=True,
          )
          marker = site / "stable" / ".version"
          stable = marker.read_text().strip() if marker.is_file() else None

          # dev first, then releases newest-first; the stable release is listed
          # once, as "vX.Y.Z (stable)".
          entries = []
          if (site / "dev").is_dir():
              entries.append({"name": "dev (unreleased)", "path": "dev"})
          for v in versions:
              if v == stable:
                  entries.append(
                      {"name": f"{v} (stable)", "path": "stable", "aliases": [v]}
                  )
              else:
                  entries.append({"name": v, "path": v})

          # /stable/ exists but no version dir claims it (only reachable by
          # hand-editing gh-pages): list it plainly instead of hiding it.
          if (site / "stable").is_dir() and not any(
              e["path"] == "stable" for e in entries
          ):
              entries.insert(
                  1 if entries and entries[0]["path"] == "dev" else 0,
                  {"name": f"{stable} (stable)" if stable else "stable",
                   "path": "stable"},
              )
          (site / "versions.json").write_text(json.dumps(entries, indent=2) + "\n")
          EOF
          }

          git -C site config user.name "github-actions[bot]"
          git -C site config user.email "41898270+github-actions[bot]@users.noreply.github.com"

          for attempt in 1 2 3; do
            apply
            git -C site add -A
            if git -C site diff --cached --quiet; then
              echo "Nothing to deploy for $DEST"
              exit 0
            fi
            git -C site commit -q -m "Deploy docs: $DEST"
            if git -C site push; then
              exit 0
            fi
            # A concurrent deploy landed first: rebuild on top of it and retry.
            echo "Push rejected, re-applying onto the latest gh-pages (attempt $attempt)"
            git -C site fetch -q origin gh-pages
            git -C site reset -q --hard FETCH_HEAD
          done
          echo "::error::could not push docs for $DEST after 3 attempts"
          exit 1