docs.yml

name: Publish docs

on:
  push:
    branches: [master]
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      version:
        type: string
        description: "Docs version (leave empty for dev build)"
        required: false
      latest:
        type: boolean
        description: "Set as 'latest' alias (ignored for dev builds; uncheck when republishing old versions)"
        default: true

permissions:
  contents: write

jobs:
  discover-languages:
    runs-on: ubuntu-latest
    outputs:
      languages: ${{ steps.find.outputs.languages }}
    steps:
      - uses: actions/checkout@v6
        with:
          sparse-checkout: docs

      - name: Find language directories
        id: find
        run: |
          # Find all directories under docs/ that contain mkdocs.yml
          langs=$(find docs -maxdepth 2 -name "mkdocs.yml" -exec dirname {} \; | xargs -n1 basename | sort | jq -R -s -c 'split("\n") | map(select(length > 0))')
          echo "languages=$langs" >> $GITHUB_OUTPUT
          echo "Found languages: $langs"

  build:
    needs: discover-languages
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        lang: ${{ fromJson(needs.discover-languages.outputs.languages) }}
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install Dependencies
        run: pip install mkdocs-material mkdocs-enumerate-headings-plugin mkdocs-quiz

      - name: Build ${{ matrix.lang }} docs
        run: mkdocs build -f docs/${{ matrix.lang }}/mkdocs.yml -d ${{ github.workspace }}/site-${{ matrix.lang }}

      - uses: actions/upload-artifact@v7
        with:
          name: site-${{ matrix.lang }}
          path: site-${{ matrix.lang }}/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Set version and alias
        id: version
        run: |
          # Determine version based on trigger
          if [ "${{ github.event_name }}" = "release" ]; then
            VERSION="${{ github.event.release.tag_name }}"
            ALIAS="latest"
            IS_RELEASE="true"
          elif [ -n "${{ github.event.inputs.version }}" ]; then
            VERSION="${{ github.event.inputs.version }}"
            # Check if this should be set as latest (default true for releases)
            if [ "${{ github.event.inputs.latest }}" = "false" ]; then
              ALIAS=""
            else
              ALIAS="latest"
            fi
            IS_RELEASE="true"
          else
            VERSION="0.dev"
            ALIAS="development"
            IS_RELEASE="false"
          fi
          echo "VERSION=$VERSION" >> $GITHUB_ENV
          echo "ALIAS=$ALIAS" >> $GITHUB_ENV
          echo "IS_RELEASE=$IS_RELEASE" >> $GITHUB_ENV
          echo "Building docs version: $VERSION (alias: $ALIAS, is_release: $IS_RELEASE)"

      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - uses: actions/download-artifact@v8
        with:
          path: artifacts

      - name: Combine language builds
        run: |
          mkdir -p combined
          # English goes to root
          cp -r artifacts/site-en/* combined/
          # Other languages go to subdirectories (discover from artifacts)
          for dir in artifacts/site-*; do
            lang=$(basename "$dir" | sed 's/site-//')
            if [ "$lang" != "en" ] && [ -d "$dir" ]; then
              mkdir -p "combined/$lang"
              cp -r "$dir"/* "combined/$lang/"
            fi
          done

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

      - name: Deploy to gh-pages
        run: |
          # Move build artifacts out of the way before checkout
          mv artifacts /tmp/artifacts
          mv combined /tmp/combined

          # Fetch gh-pages if it exists
          git fetch origin gh-pages:gh-pages 2>/dev/null || true

          # Check if gh-pages exists
          if git show-ref --verify --quiet refs/heads/gh-pages; then
            git checkout gh-pages
            # Remove old version directories
            rm -rf "$VERSION"
            [ -n "$ALIAS" ] && rm -rf "$ALIAS"
          else
            git checkout --orphan gh-pages
            git rm -rf . 2>/dev/null || true
          fi

          # Copy combined site to version directory
          cp -r /tmp/combined "$VERSION"
          [ -n "$ALIAS" ] && cp -r /tmp/combined "$ALIAS"

          # Update versions.json for mike compatibility
          python3 << 'EOF'
          import json
          import os
          from pathlib import Path

          version = os.environ["VERSION"]
          alias = os.environ.get("ALIAS", "")
          is_release = os.environ["IS_RELEASE"] == "true"

          versions_file = Path("versions.json")
          if versions_file.exists():
              versions = json.loads(versions_file.read_text())
          else:
              versions = []

          # Remove existing entry for this version
          versions = [v for v in versions if v.get("version") != version]

          if alias == "latest":
              # Remove 'latest' alias from other versions (only when setting new latest)
              for v in versions:
                  if "aliases" in v:
                      v["aliases"] = [a for a in v["aliases"] if a != "latest"]

          # Create new entry
          new_entry = {
              "version": version,
              "title": version,
              "aliases": [alias] if alias else []
          }

          if is_release:
              # Insert at the beginning (most recent release first)
              versions.insert(0, new_entry)
          else:
              # Dev version goes at the end
              versions.append(new_entry)

          versions_file.write_text(json.dumps(versions, indent=2))
          EOF

          # Commit and push
          git add -A
          git commit -m "Deploy $VERSION docs" --allow-empty
          # Use --force for dev builds to handle any conflicts
          if [ "$IS_RELEASE" = "true" ]; then
            git push origin gh-pages
          else
            git push origin gh-pages --force
          fi

      - name: Pin GitHub Codespaces version
        if: env.IS_RELEASE == 'true'
        run: |
          # Update Codespaces links to use the release version
          find "$VERSION" -type f -exec sed -i "s|ref=master|ref=$VERSION|g" {} +
          git add "$VERSION"
          if [ -n "$ALIAS" ]; then
            find "$ALIAS" -type f -exec sed -i "s|ref=master|ref=$VERSION|g" {} +
            git add "$ALIAS"
          fi
          git status
          git commit -m "[automated] Pin GitHub Codespaces link versions" || true
          git push origin gh-pages