docs-site.yml

# Generates and deploys static site to GitHub Pages
# https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
# Reference workflow: https://github.com/actions/starter-workflows/blob/main/pages/jekyll-gh-pages.yml
name: Metro Docs Site

on:
  push:
    branches: ["main"]
    tags:
      - '*.*.*' # Matches semantic versioning tags

  # PR trigger for docs dry run when requirements change
  pull_request:
    paths:
      - '.github/workflows/mkdocs-requirements.txt'

  # Allows manual deployements (if needed)
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow pushing to `gh-pages` branch
permissions:
  contents: write
  pages: write
  id-token: write

# Only allow one docs deployment at a time per type, prioritize tagged releases
concurrency:
  group: ${{ startsWith(github.ref, 'refs/tags/') && 'pages-release' || 'pages-dev' }}
  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}

jobs:
  # Metro docs site build job
  docs-site:
    runs-on: ubuntu-latest
    if: github.repository == 'zacsweers/metro' && github.event_name != 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0 # Full history needed for git-revision-date-localized plugin

      - name: Setup Gradle
        uses: ./.github/actions/setup-gradle
        with:
          encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
          cache-read-only: ${{ github.ref != 'refs/heads/main' }}

      - name: Generate API docs
        # NOTE: The `dokkaPublications.html` task is pre-configured to generate HTML in `/docs/api`.
        run: ./scripts/generate_docs_dokka.sh
        env:
          GRADLE_OPTS: -Xmx4g # Dokka can be memory intensive, so we increase the heap size

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install docs dependencies
        run: |
          pip install --requirement .github/workflows/mkdocs-requirements.txt

      - name: Copy documentation files
        run: ./scripts/copy_docs_files.sh

      - name: Validate documentation file mappings
        run: ./scripts/copy_docs_files_mapping_validator.sh

      - name: Extract Metro version from gradle.properties
        id: version
        run: |
          METRO_VERSION=$(grep "VERSION_NAME=" gradle.properties | cut -d'=' -f2)
          echo "METRO_VERSION=$METRO_VERSION" >> $GITHUB_OUTPUT
          echo "Extracted version: $METRO_VERSION"

      - name: Validate version format
        run: |
          VERSION="${{ steps.version.outputs.METRO_VERSION }}"
          
          # Check if version is empty
          if [[ -z "$VERSION" ]]; then
            echo "ERROR: VERSION_NAME is empty in gradle.properties"
            exit 1
          fi
          
          # Check if version matches x.y.z, x.y.z-SNAPSHOT, or x.y.z-<prerelease> pattern
          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(SNAPSHOT|[a-zA-Z]+[0-9]*))?$ ]]; then
            echo "ERROR: VERSION_NAME '$VERSION' does not match expected format:"
            echo "   Expected: x.y.z, x.y.z-SNAPSHOT, or x.y.z-<prerelease> (e.g., 1.2.3, 1.2.3-SNAPSHOT, 1.0.0-RC1)"
            echo "   Actual: $VERSION"
            exit 1
          fi
          
          echo "Version format is valid: $VERSION"

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

      - name: Fetch gh-pages branch
        run: |
          # Fetch the gh-pages branch to ensure we have the latest state
          git fetch origin gh-pages:gh-pages || echo "gh-pages branch doesn't exist yet (first deployment)"

      - name: Show current mike versions
        run: |
          echo "Current mike versions available:"
          mike list || echo "No docs site versions found (likely first deployment)"

      - name: Validate docs build with Zensical
        run: |
          echo "Building docs for validation with Zensical..."
          zensical build

          echo "Validating directory URL structure..."
          # Check that use_directory_urls: true is working correctly
          # This setting converts installation.md -> installation/index.html
          # enabling clean URLs like /installation/ instead of /installation.html
          if [ -f "site/installation/index.html" ]; then
            echo "✔ Directory URLs are working correctly (installation/index.html exists)"
          else
            echo "✖ Directory URLs validation failed - installation/index.html not found"
            echo "This suggests use_directory_urls: true is not working properly"
            exit 1
          fi

          echo "Cleaning up build directory..."
          rm -rf site
          echo "Docs validation completed successfully"

      - name: Re-sync gh-pages branch before deployment
        run: |
          # Safely update local gh-pages to match remote state to avoid push conflicts
          git fetch origin gh-pages
          git update-ref refs/heads/gh-pages origin/gh-pages

      - name: Deploy SNAPSHOT Docs with mike
        if: ${{ success() && contains(steps.version.outputs.METRO_VERSION, 'SNAPSHOT') }}
        run: mike deploy --update-aliases --push ${{ steps.version.outputs.METRO_VERSION }} snapshot

      - name: Deploy Release Docs with mike
        if: ${{ success() && !contains(steps.version.outputs.METRO_VERSION, 'SNAPSHOT') }}
        run: mike deploy --update-aliases --push ${{ steps.version.outputs.METRO_VERSION }} latest

      - name: Delete old doc versions
        run: |
          git fetch origin gh-pages --depth=1
          ./scripts/delete_old_version_docs.sh

  # Docs dry run job for PRs that change requirements.txt
  docs-dry-run:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0 # Full history needed for git-revision-date-localized plugin

      - name: Setup Gradle
        uses: ./.github/actions/setup-gradle
        with:
          encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
          cache-read-only: true

      - name: Generate API docs
        run: ./scripts/generate_docs_dokka.sh
        env:
          GRADLE_OPTS: -Xmx4g # Dokka can be memory intensive, so we increase the heap size

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install docs dependencies
        run: |
          pip install --requirement .github/workflows/mkdocs-requirements.txt

      - name: Copy documentation files
        run: ./scripts/copy_docs_files.sh

      - name: Validate documentation file mappings
        run: ./scripts/copy_docs_files_mapping_validator.sh

      - name: Build docs (dry run with Zensical)
        run: |
          echo "Building docs as a dry run to verify requirements and other configs are working..."
          zensical build

          echo "Validating directory URL structure..."
          # Verify that use_directory_urls: true configuration is effective
          # This creates installation/index.html from installation.md, enabling
          # clean URLs (/installation/) instead of file URLs (/installation.html)
          if [ -f "site/installation/index.html" ]; then
            echo "✔ Directory URLs are working correctly (installation/index.html exists)"
          else
            echo "✖ Directory URLs validation failed - installation/index.html not found"
            exit 1
          fi

          echo "Cleaning up build directory..."
          rm -rf site
          echo "✔ Docs build and validation completed successfully!"