deploy-docs.yml

name: Build and Deploy Documentation

on:
  push:
    branches:
      - develop
      - test
      - main
  workflow_dispatch:  # manual trigger from Actions UI

# One run per branch - concurrent runs race on the cache commit-back and the
# gh-pages deploy. Queue, don't cancel (a half-written cache is worse).
concurrency:
  group: deploy-docs-${{ github.ref }}
  cancel-in-progress: false

jobs:
  deploy_docs:
    name: Build and Deploy Docs
    runs-on: ubuntu-latest

    # Force bash for every run step. Inside a container the default is sh.
    defaults:
      run:
        shell: bash

    container:
      # Pinned (May 2026).
      image: mckeea/quarto-doc-builder:1.0.4
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          # develop/test only diff HEAD^..HEAD, so a shallow clone is enough
          fetch-depth: ${{ (github.ref_name == 'main' || startsWith(github.ref, 'refs/heads/test-')) && '0' || '50' }}
          fetch-tags: true

      - name: Upgrade panflute to latest version
        run: pip install --no-cache-dir --break-system-packages --upgrade panflute

      - name: Mark repo as safe for Git
        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"

      - name: Show commit history
        run: git log --oneline -n 5

      - name: Get changed .qmd files on current branch
        run: |
          (git diff --name-only HEAD^ HEAD | grep -E '\.qmd$' || true) > modified_docs_list.txt
          echo "Modified .qmd files:"
          cat modified_docs_list.txt

      - name: Set up git user for commits
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"

      - name: Detect test mode for dry-run
        id: test_mode
        run: |
          if [[ "$GITHUB_REF" == refs/heads/test-* ]]; then
            echo "dry_run=true" >> "$GITHUB_OUTPUT"
            echo "🔍 Test branch detected - enabling DRY_RUN mode"
          else
            echo "dry_run=false" >> "$GITHUB_OUTPUT"
            echo "✅ Production branch - normal execution"
          fi

      # Runs in the container - it carries google-genai + tiktoken.
      - name: Update intros, keywords, versions & changelogs
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          DRY_RUN: ${{ steps.test_mode.outputs.dry_run }}
        run: |
          DRY_RUN_FLAG=()
          if [[ "$DRY_RUN" == "true" ]]; then DRY_RUN_FLAG=(--dry-run); fi
          # --versions runs only on main (real releases) and test-* (dry-run tests).
          # develop/test skip it: no version bumps there, and no tags to diff against.
          if [[ "$GITHUB_REF_NAME" == "main" || "$GITHUB_REF" == refs/heads/test-* ]]; then
            python .github/scripts/ai/update_documentation.py --intros modified_docs_list.txt --versions "${DRY_RUN_FLAG[@]}"
          else
            python .github/scripts/ai/update_documentation.py --intros modified_docs_list.txt "${DRY_RUN_FLAG[@]}"
          fi

      - name: Describe images (develop only — cache propagates to test/main)
        if: github.ref_name == 'develop'
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          # Describe images under DOCS/*-media/. Keyed by image md5, so only
          # new or changed ones hit the API. Cache is committed back next step.
          python .github/scripts/ai/describe_images.py

      - name: Commit updated LLM cache and version history
        if: steps.test_mode.outputs.dry_run == 'false'
        run: |
          git add .llm_cache .version-history

          if git diff --cached --quiet; then
            echo "No changes to commit."
          else
            git commit -m "Update LLM cache and version history [skip ci]"
            git push origin HEAD
          fi

      - name: Build Docs
        run: .github/scripts/build/build-docs.sh

      - name: Commit updated non-browsable doc map
        run: |
          git add .github/non_browsable_doc_map.json

          if git diff --cached --quiet; then
            echo "No changes to commit."
          else
            git commit -m "Update non-browsable doc map [skip ci]"
            git push origin HEAD
          fi

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: DOCS/_site
          target-folder: ${{ github.ref_name }}
          clean: true
          token: ${{ secrets.GITHUB_TOKEN }}