docs.yaml

name: Update Docs

on:
  push:
    branches:
      - stable
    paths:
      - 'lib/**'
      - 'pubspec.yaml'
      - '.github/workflows/docs.yaml'
  pull_request:
    branches:
      - stable
    paths:
      - 'lib/**'
      - 'pubspec.yaml'
      - '.github/workflows/docs.yaml'

jobs:
  update-docs:
    permissions:
      contents: write
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.get_version.outputs.version }}
      pr_exists: ${{ steps.update_docs_branch.outputs.pr_exists }}
      docs_changed: ${{ steps.update_docs_branch.outputs.docs_changed }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Dart
        uses: dart-lang/setup-dart@v1

      - name: Install dependencies
        run: dart pub get

      - name: Analyze project source
        run: dart analyze

      - name: Get version from pubspec.yaml
        id: get_version
        run: |
          VERSION=$(grep '^version:' pubspec.yaml | head -n1 | cut -d ' ' -f2)
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Generate docs
        run: dart doc

      - name: Prepare docs for branch
        run: |
          # Store the generated docs in a temporary location
          cp -r doc/api /tmp/generated_docs

      - name: Create or update docs branch
        id: update_docs_branch
        env:
          VERSION: ${{ steps.get_version.outputs.version }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          BRANCH=docs-for-$VERSION
          
          # Check for existing PR from docs branch to gh-pages
          PR_EXISTS=$(gh pr list --base gh-pages --head "$BRANCH" --state open --json number --jq 'length > 0' || echo false)
          echo "pr_exists=$PR_EXISTS" >> $GITHUB_OUTPUT
          
          # Check if docs branch exists
          if git ls-remote --exit-code --heads origin "$BRANCH"; then
            echo "Branch $BRANCH exists, checking it out..."
            git fetch origin "$BRANCH"
            git checkout "$BRANCH"
            git reset --hard origin/$BRANCH
          else
            echo "Branch $BRANCH does not exist, creating from gh-pages..."
            # Create docs branch from gh-pages so there is a common ancestor
            git fetch origin gh-pages:gh-pages || git checkout --orphan gh-pages
            git checkout gh-pages || git checkout --orphan gh-pages
            git checkout -b "$BRANCH"
          fi
          
          # Clean up everything except .git
          find . -mindepth 1 -maxdepth 1 ! -name '.git' ! -name '.' ! -name '..' -exec rm -rf {} +
          
          # Move generated docs from temp location to root
          shopt -s dotglob
          mv /tmp/generated_docs/* .
          shopt -u dotglob

          # Add all files
          git add .

          echo "Files in working directory:"
          ls -alR
          echo "Files staged for commit:"
          git diff --cached --name-status
          echo "Files changed (not staged):"
          git diff --name-status
          echo "Now checking for changes..."

          # Compare with gh-pages branch
          git fetch origin gh-pages:gh-pages || true
          if git diff --cached --quiet origin/gh-pages --; then
            echo "Docs branch is identical to gh-pages. Checking for open PR..."
            if [ "$PR_EXISTS" = "false" ]; then
              echo "No open PR. Deleting branch."
              # Checkout gh-pages or orphan so docs branch is not in use
              git fetch origin gh-pages:gh-pages || true
              git checkout gh-pages 2>/dev/null || git checkout --orphan gh-pages
              git branch -D "$BRANCH" || true
              if git ls-remote --exit-code --heads origin "$BRANCH"; then
                git push origin --delete "$BRANCH" || true
              else
                echo "Remote branch $BRANCH does not exist, nothing to delete."
              fi
              echo "docs_changed=false" >> $GITHUB_OUTPUT
              exit 0
            else
              echo "Open PR exists. Not deleting branch."
              echo "docs_changed=false" >> $GITHUB_OUTPUT
              exit 0
            fi
          fi

          # Check if there are any changes to commit (FIXED LOGIC)
          if ! git diff --cached --quiet; then
            echo "Changes detected, committing..."
            # Get the commit SHA that triggered the workflow
            TRIGGER_COMMIT=${{ github.sha }}
            COMMIT_MSG="Update docs for $VERSION (generated from $TRIGGER_COMMIT)"
            git commit -m "$COMMIT_MSG"
            git push -f origin "$BRANCH"
            echo "docs_changed=true" >> $GITHUB_OUTPUT
          else
            echo "No changes to commit."
            echo "docs_changed=false" >> $GITHUB_OUTPUT
          fi

  create-docs-pr:
    needs: [update-docs]
    permissions:
      contents: write
      pull-requests: write
    runs-on: ubuntu-latest
    if: needs.update-docs.outputs.pr_exists == 'false' && needs.update-docs.outputs.docs_changed == 'true'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Create or update PR to gh-pages
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ needs.update-docs.outputs.version }}
        run: |
          BRANCH=docs-for-$VERSION
          PR_TITLE="Docs for $VERSION"

          TRIGGER_COMMIT=${{ github.sha }}
          PR_BODY="Automated documentation update for version $VERSION.

          Triggered by commit $TRIGGER_COMMIT."

          # If triggered by a PR, mention it in the PR body
          if [ "${{ github.event_name }}" = "pull_request" ] && [ -n "${{ github.event.pull_request.number }}" ]; then
            PR_BODY="$PR_BODY
            
            Triggered by #${{ github.event.pull_request.number }}"
          fi

          # Check if a PR already exists
          PR_NUMBER=$(gh pr list --base gh-pages --head "$BRANCH" --state open --json number --jq '.[0].number' || echo "")
          if [ -z "$PR_NUMBER" ]; then
            echo "Creating new PR..."
            gh pr create --base gh-pages --head "$BRANCH" --title "$PR_TITLE" --body "$PR_BODY"
          else
            echo "PR #$PR_NUMBER already exists. Updating title and body."
            gh pr edit "$PR_NUMBER" --title "$PR_TITLE" --body "$PR_BODY"
          fi