api-docs-backfill.yml

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


# Manual fallback for (re)building a release tag's API docs when the automatic
# deploy (api-docs.yml, on tag push) didn't run or failed. Builds entirely from
# the tag -- a release carries its own source plus the docs tooling (docs-site/,
# scripts/) -- and opens a PR against gh-pages for review instead of deploying
# directly.
#
# Only works for tags that already carry the docs tooling. Tags cut before the
# docs tooling landed (no docs-site/ or scripts/generate-api-docs.sh) will fail.
#
# How to trigger:
#   - UI: Actions tab -> "API Reference Backfill" -> "Run workflow", pick the
#     package and enter the version tag (e.g. v1.0.0).
#   - CLI: gh workflow run api-docs-backfill.yml -f package=core -f version=v1.0.0
#   The package + version must match an existing release tag
#   (toolbox-<package>-<version>, e.g. toolbox-core-v1.0.0). Review and merge the
#   resulting gh-pages PR to publish.
name: "API Reference Backfill"
on:
  workflow_dispatch:
    inputs:
      package:
        description: "Package to backfill"
        type: choice
        options: [core, adk, langchain, llamaindex]
        required: true
      version:
        description: "Version tag to build, e.g. v1.0.0"
        type: string
        required: true

# Scope per version: each run produces an independent branch/PR, so runs for
# different versions can proceed in parallel. A shared group with
# cancel-in-progress: false would make GitHub cancel a pending run whenever a
# newer one queues, silently dropping versions when several are dispatched.
concurrency:
  group: api-docs-backfill-${{ github.event.inputs.package }}-${{ github.event.inputs.version }}
  cancel-in-progress: false

jobs:
  backfill:
    # Never run on forks; docs deploy only from the upstream repository.
    if: github.repository == 'googleapis/mcp-toolbox-sdk-python'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      # Build entirely from the tag: its source and the docs tooling (docs-site/,
      # scripts/) all ship in the release, so no overlay from main is needed.
      - name: Checkout tagged source
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
        with:
          ref: refs/tags/toolbox-${{ inputs.package }}-${{ inputs.version }}
          submodules: recursive
          fetch-depth: 0
          persist-credentials: false

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

      - name: Install doc generator
        run: |
          # pydoc-markdown parses the SDK source statically (no install/import of
          # the packages), so no package build step is needed -- unlike the JS
          # pipeline, which compiles types before TypeDoc runs.
          pip install -r docs-site/requirements.txt

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3
        with:
          hugo-version: '0.152.2'
          extended: true

      - name: Install PostCSS Dependencies
        run: |
          # npm ci installs the exact versions from docs-site/package-lock.json
          # into docs-site/node_modules (where Hugo's PostCSS looks), so the
          # build is reproducible -- a broken upstream patch can't be pulled in.
          # docs-site/package.json pins postcss/postcss-cli/autoprefixer; the
          # lockfile freezes their transitive deps.
          cd docs-site
          npm ci

      - name: Build docs
        env:
          PKG: ${{ inputs.package }}
          VER: ${{ inputs.version }}
          # Deploys only run upstream (see job-level guard), so always use the
          # production domain.
          BASE_URL: https://py.mcp-toolbox.dev/
        run: |
          chmod +x scripts/generate-api-docs.sh
          ./scripts/generate-api-docs.sh "$PKG" "$VER" "$BASE_URL"

      # Open a PR into gh-pages instead of deploying directly, so a human reviews
      # before the page goes live. Overlaying the build onto a clone of the live
      # gh-pages tree mirrors keep_files: true — existing files (other versions,
      # CNAME, .nojekyll) are preserved and the PR diff is just this version.
      - name: Open PR against gh-pages
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PKG: ${{ inputs.package }}
          VER: ${{ inputs.version }}
        run: |
          set -euo pipefail
          BRANCH="backfill/${PKG}-${VER}"
          git config --global user.name "github-actions[bot]"
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"

          WORK="$(mktemp -d)"
          git clone --depth 1 --branch gh-pages --single-branch \
            "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$WORK"
          cp -R "${GITHUB_WORKSPACE}/docs-site/public/." "$WORK/"

          cd "$WORK"
          git checkout -B "$BRANCH"
          git add -A
          if git diff --cached --quiet; then
            echo "No documentation changes for ${PKG} ${VER}; skipping PR."
            exit 0
          fi
          git commit -m "docs(api): backfill ${PKG} ${VER}"
          git push -f origin "$BRANCH"

          if gh pr view "$BRANCH" --json number >/dev/null 2>&1; then
            echo "PR already open for ${BRANCH}; branch updated."
          else
            gh pr create --base gh-pages --head "$BRANCH" \
              --title "docs(api): backfill ${PKG} ${VER}" \
              --body "Automated API reference backfill for \`${PKG}/${VER}\`, built from the release tag. Merging publishes to gh-pages (additive)."
          fi