api_reference.yml

name: Update API Reference Documentation

on:
  push:
    branches: [main, master, dev]
    paths:
      - "kaira/**/*.py"
      - "scripts/generate_api_reference.py"
  pull_request:
    branches: [main, master, dev]
    paths:
      - "kaira/**/*.py"
      - "scripts/generate_api_reference.py"
  workflow_dispatch: # Allow manual triggering

# Cancel previous runs if a new push happens
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  update-api-reference:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0 # Need full history for proper git operations

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13.2" # Use same as main CI
          cache: "pip"

      - name: Cache Python dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-api-${{ hashFiles('requirements*.txt', 'pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-pip-api-
            ${{ runner.os }}-pip-

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

      - name: Generate API reference documentation
        run: |
          echo "🔄 Generating API reference documentation..."
          python scripts/generate_api_reference.py docs/api_reference.rst
          echo "✅ API reference generation completed"

      - name: Check for changes
        id: changes
        run: |
          echo "🔍 Checking for changes in API reference..."

          if [ ! -f "docs/api_reference.rst" ]; then
            echo "❌ API reference file was not generated"
            exit 1
          fi

          # Check if file has meaningful content
          if [ $(wc -l < "docs/api_reference.rst") -lt 10 ]; then
            echo "❌ API reference file seems too small or empty"
            exit 1
          fi

          # Check for actual changes
          if git diff --quiet docs/api_reference.rst; then
            echo "ℹ️ No changes detected in API reference"
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "📝 Changes detected in API reference"
            echo "Changed lines:"
            git diff --stat docs/api_reference.rst
            echo "changed=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit and push changes
        if: steps.changes.outputs.changed == 'true' && github.event_name == 'push'
        run: |
          echo "📝 Committing API reference changes..."

          # Configure git with better identity
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # Add the file and commit
          git add docs/api_reference.rst

          # Create commit with more context
          commit_msg="docs: Auto-update API reference documentation

          Updated API reference for commit ${{ github.sha }}
          Triggered by: ${{ github.event_name }}
          Branch: ${{ github.ref_name }}

          [skip ci]"

          git commit -m "$commit_msg"

          # Push with retry logic
          max_attempts=3
          attempt=1

          while [ $attempt -le $max_attempts ]; do
            echo "📤 Push attempt $attempt of $max_attempts..."
            if git push; then
              echo "✅ Successfully pushed API reference updates"
              break
            else
              if [ $attempt -eq $max_attempts ]; then
                echo "❌ Failed to push after $max_attempts attempts"
                exit 1
              fi
              echo "⚠️ Push failed, retrying in 5 seconds..."
              sleep 5
              git pull --rebase
              attempt=$((attempt + 1))
            fi
          done

      - name: Comment on PR
        if: steps.changes.outputs.changed == 'true' && github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');

            // Get diff statistics
            const { execSync } = require('child_process');
            let diffStats = '';
            try {
              diffStats = execSync('git diff --stat docs/api_reference.rst', { encoding: 'utf8' });
            } catch (error) {
              diffStats = 'Unable to get diff statistics';
            }

            const body = `🤖 **API Reference Documentation Updated**

            The API reference documentation has been automatically updated based on the code changes in this PR.

            ### Changes Summary:
            \`\`\`
            ${diffStats}
            \`\`\`

            ### Files Modified:
            - \`docs/api_reference.rst\`

            > 💡 **Note**: This update was automatically generated by analyzing the Python code changes in the \`kaira/\` directory.

            <details>
            <summary>🔍 View API Reference Diff</summary>

            The updated API reference will be visible once this PR is merged and the documentation is rebuilt.

            </details>`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            })

      - name: Generate job summary
        if: always()
        run: |
          echo "# 📚 API Reference Documentation Update" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ steps.changes.outputs.changed }}" = "true" ]; then
            echo "✅ **Status**: API reference documentation was updated" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "### Changes Made:" >> $GITHUB_STEP_SUMMARY
            echo "- Updated \`docs/api_reference.rst\`" >> $GITHUB_STEP_SUMMARY
            echo "- Detected changes in Python modules under \`kaira/\`" >> $GITHUB_STEP_SUMMARY

            if [ "${{ github.event_name }}" = "push" ]; then
              echo "- Automatically committed and pushed changes" >> $GITHUB_STEP_SUMMARY
            elif [ "${{ github.event_name }}" = "pull_request" ]; then
              echo "- Added comment to PR with update details" >> $GITHUB_STEP_SUMMARY
            fi
          else
            echo "ℹ️ **Status**: No changes needed" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "The API reference documentation is already up to date." >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Trigger Information:" >> $GITHUB_STEP_SUMMARY
          echo "- **Event**: ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Branch**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Commit**: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY