docs.yml

name: Deploy MkDocs Documentation

on:
  push:
    branches:
      - main
      # Note: Only deploy from main as "latest" documentation
      # Release branches (release/2.4, release/2.5, release/2.6) are for stabilization and may contain
      # unstable changes. Production docs should reference the tagged release.
    paths:
      # Only files that are part of the MkDocs site (see mkdocs.yml nav)
      - 'docs/index.md'
      - 'docs/architecture/ARCHITECTURE.md'
      - 'docs/architecture/TESTING_STRATEGY.md'
      - 'docs/CI_CD.md'
      - 'docs/legal.md'
      - 'docs/api/**'
      - 'docs/guides/**'
      - 'docs/prd/**'
      - 'docs/releases/**'
      - 'docs/wip/**'
      - 'docs/javascripts/**'
      - 'docs/architecture/**'
      - 'docs/adr/**'
      - 'docs/rfc/**'
      - 'docs/ci/**'
      - 'mkdocs.yml'
      - '**.py'  # Python files for API docs (mkdocstrings)
      - 'README.md'
  pull_request:
    branches: [ "main", "release/2.4", "release/2.5", "release/2.6" ]
    # PRs can still be tested against both branches, but only main deploys
    paths:
      # Only files that are part of the MkDocs site (see mkdocs.yml nav)
      - 'docs/index.md'
      - 'docs/architecture/ARCHITECTURE.md'
      - 'docs/architecture/TESTING_STRATEGY.md'
      - 'docs/CI_CD.md'
      - 'docs/legal.md'
      - 'docs/api/**'
      - 'docs/guides/**'
      - 'docs/prd/**'
      - 'docs/releases/**'
      - 'docs/wip/**'
      - 'docs/javascripts/**'
      - 'docs/architecture/**'
      - 'docs/adr/**'
      - 'docs/rfc/**'
      - 'docs/ci/**'
      - 'mkdocs.yml'
      - '**.py'  # Python files for API docs (mkdocstrings)
      - 'README.md'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write
  actions: read  # Required to download artifacts from other workflows

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
      actions: read
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.11.8"
          cache: "pip"
          cache-dependency-path: docs/requirements.txt

      - name: Install documentation dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt
          pip install -e .

      - name: Build MkDocs site
        run: |
          PYTHONPATH="${PYTHONPATH}:$(pwd)"
          export PYTHONPATH
          # Generate deployment metadata
          DEPLOY_TIME=$(date -u +"%Y-%m-%d %H:%M UTC")
          DEPLOY_BRANCH="${{ github.ref_name }}"
          DEPLOY_SHA="${{ github.sha }}"
          DEPLOY_SHA_SHORT="${DEPLOY_SHA:0:7}"
          DEPLOY_URL="https://github.com/${{ github.repository }}/commit/${DEPLOY_SHA}"

          # Create deploy-info.json
          mkdir -p .build/site
          cat > .build/site/deploy-info.json << EOF
          {
            "timestamp": "${DEPLOY_TIME}",
            "branch": "${DEPLOY_BRANCH}",
            "commit": "${DEPLOY_SHA_SHORT}",
            "commitUrl": "${DEPLOY_URL}"
          }
          EOF

          mkdocs build --strict

      - name: Download CI metrics artifact
        if: github.event_name == 'push'
        uses: dawidd6/action-download-artifact@v21
        with:
          workflow: python-app.yml
          name: metrics
          path: .build/site/metrics
          if_no_artifact_found: warn
          search_artifacts: true
        continue-on-error: true

      - name: Download nightly metrics artifact
        if: github.event_name == 'push'
        uses: dawidd6/action-download-artifact@v21
        with:
          workflow: nightly.yml
          name: nightly-metrics
          path: .build/site/metrics
          if_no_artifact_found: warn
          search_artifacts: true
        continue-on-error: true

      - name: Consolidate metrics files
        if: github.event_name == 'push'
        run: |
          # Move any files from subdirectories to main metrics directory
          find .build/site/metrics -name "*.json" -o -name "*.jsonl" -o -name "*.html" | while IFS= read -r file; do
            if [ "$(dirname "$file")" != ".build/site/metrics" ]; then
              mv "$file" .build/site/metrics/
            fi
          done

          # List what we have
          echo "=== Metrics files ==="
          ls -la .build/site/metrics/ || echo "No metrics directory"

      - name: Merge metrics artifacts for unified dashboard
        if: github.event_name == 'push'
        run: |
          mkdir -p .build/site/metrics

          # Check if unified dashboard exists (from either CI or nightly)
          if [ -f ".build/site/metrics/index.html" ]; then
            echo "✅ Unified dashboard found"
          else
            echo "⚠️ No dashboard found, creating placeholder"
            cat > .build/site/metrics/index.html << 'EOF'
          <!DOCTYPE html>
          <html>
          <head>
            <title>Metrics Dashboard</title>
            <style>
              body { font-family: system-ui, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
              h1 { color: #333; }
              p { color: #666; line-height: 1.6; }
              a { color: #0066cc; }
            </style>
          </head>
          <body>
            <h1>📊 Metrics Dashboard</h1>
            <p>No metrics data available yet.</p>
            <p>Metrics are generated after CI runs on the main branch or scheduled nightly runs.</p>
            <p><a href="/">← Back to Documentation</a></p>
          </body>
          </html>
          EOF
          fi

          # Ensure both CI and nightly data files are in the same directory
          # CI files should be: latest-ci.json, history-ci.jsonl
          # Nightly files should be: latest-nightly.json, history-nightly.jsonl
          # The unified dashboard will look for these files in the same directory

          if [ -f ".build/site/metrics/latest-ci.json" ]; then
            echo "✅ CI metrics data available"
          else
            echo "⚠️ No CI metrics artifact, writing placeholder to avoid dashboard JSON parse errors"
            echo '{"timestamp":null,"commit":null,"branch":null,"metrics":{},"trends":{},"alerts":[{"severity":"info","metric":"ci","message":"No CI metrics yet. Data is generated after pushes to main."}]}' > .build/site/metrics/latest-ci.json
          fi

          if [ -f ".build/site/metrics/latest-nightly.json" ]; then
            echo "✅ Nightly metrics data available"
          else
            echo "⚠️ No nightly metrics artifact, writing placeholder"
            echo '{"timestamp":null,"commit":null,"branch":null,"metrics":{},"trends":{},"alerts":[{"severity":"info","metric":"nightly","message":"No nightly metrics yet. Data is generated by scheduled nightly runs."}]}' > .build/site/metrics/latest-nightly.json
          fi

          echo "📊 Unified dashboard will display data from available sources"

      - name: Upload artifact
        if: github.event_name == 'push'
        uses: actions/upload-pages-artifact@v5
        with:
          path: .build/site

  deploy:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5