docs.yml

name: Docs

on:
  push:
    branches:
      - develop
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'
  release:
    types:
      - published
  workflow_dispatch:
    inputs:
      docs_version:
        description: 'Docs version to publish, e.g. 1.1.0. Leave blank to publish develop.'
        required: false
        type: string
      source_ref:
        description: 'Git ref to build from. Defaults to docs_version prefixed with v when available.'
        required: false
        type: string
      update_latest:
        description: 'Also move latest alias/default redirect to this version. Ignored when docs_version is blank.'
        required: false
        default: false
        type: boolean

permissions:
  contents: read

concurrency:
  group: docs-gh-pages
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Resolve docs metadata
        id: docs
        shell: bash
        env:
          INPUT_DOCS_VERSION: ${{ github.event.inputs.docs_version }}
          INPUT_SOURCE_REF: ${{ github.event.inputs.source_ref }}
          INPUT_UPDATE_LATEST: ${{ github.event.inputs.update_latest }}
          RELEASE_PRERELEASE: ${{ github.event.release.prerelease }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: |
          set -euo pipefail

          validate_docs_version() {
            local version="$1"

            if [[ ! "$version" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
              echo "::error::docs_version may only contain letters, numbers, dots, underscores, and hyphens."
              exit 1
            fi
          }

          if [[ "$GITHUB_EVENT_NAME" == "push" ]]; then
            echo "checkout_ref=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
            echo "docs_version=develop" >> "$GITHUB_OUTPUT"
            echo "update_latest=auto" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          if [[ "$GITHUB_EVENT_NAME" == "release" ]]; then
            docs_version="${RELEASE_TAG#v}"

            if [[ -z "$docs_version" ]]; then
              echo "::error::Release tag must contain a version, e.g. v1.1.0."
              exit 1
            fi

            validate_docs_version "$docs_version"

            echo "checkout_ref=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
            echo "docs_version=$docs_version" >> "$GITHUB_OUTPUT"

            if [[ "$RELEASE_PRERELEASE" == "true" ]]; then
              echo "update_latest=false" >> "$GITHUB_OUTPUT"
            else
              echo "update_latest=true" >> "$GITHUB_OUTPUT"
            fi

            exit 0
          fi

          if [[ -z "$INPUT_DOCS_VERSION" ]]; then
            source_ref="$INPUT_SOURCE_REF"
            if [[ -z "$source_ref" ]]; then
              source_ref="develop"
            fi

            echo "checkout_ref=$source_ref" >> "$GITHUB_OUTPUT"
            echo "docs_version=develop" >> "$GITHUB_OUTPUT"
            echo "update_latest=auto" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          docs_version="${INPUT_DOCS_VERSION#v}"
          validate_docs_version "$docs_version"

          source_ref="$INPUT_SOURCE_REF"
          if [[ -z "$source_ref" ]]; then
            source_ref="v$docs_version"
          fi

          echo "checkout_ref=$source_ref" >> "$GITHUB_OUTPUT"
          echo "docs_version=$docs_version" >> "$GITHUB_OUTPUT"

          if [[ "$INPUT_UPDATE_LATEST" == "true" ]]; then
            echo "update_latest=true" >> "$GITHUB_OUTPUT"
          else
            echo "update_latest=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ steps.docs.outputs.checkout_ref }}

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.x'

      - name: Install docs dependencies
        run: pip install -r docs/requirements.txt

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

      - name: Build docs
        run: mkdocs build --strict

      - name: Fetch Pages branch
        run: git fetch origin gh-pages --depth=1 || true

      - name: Deploy versioned docs
        env:
          DOCS_VERSION: ${{ steps.docs.outputs.docs_version }}
          UPDATE_LATEST: ${{ steps.docs.outputs.update_latest }}
        shell: bash
        run: |
          set -euo pipefail

          should_update_latest="$UPDATE_LATEST"

          if [[ "$should_update_latest" == "auto" ]]; then
            versions_file="$RUNNER_TEMP/docs-versions.json"

            if git show origin/gh-pages:versions.json > "$versions_file" 2>/dev/null \
              && python3 - "$versions_file" <<'PY'
          import json
          import re
          import sys

          with open(sys.argv[1], encoding='utf-8') as handle:
              versions = json.load(handle)

          stable_version = re.compile(r'^[0-9]+\.[0-9]+\.[0-9]+$')

          for item in versions:
              if stable_version.fullmatch(str(item.get('version', ''))):
                  sys.exit(0)

          sys.exit(1)
          PY
            then
              should_update_latest=false
            else
              should_update_latest=true
            fi
          fi

          if [[ "$should_update_latest" == "true" ]]; then
            mike deploy --push --update-aliases "$DOCS_VERSION" latest
            mike set-default --push latest
          else
            mike deploy --push "$DOCS_VERSION"
          fi