api-docs.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.


name: "API Reference Deployment"
on:
  push:
    branches: [ 'main' ]
    tags: [ '**' ]
  workflow_dispatch:

concurrency:
  group: api-docs-deploy
  cancel-in-progress: false

jobs:
  deploy:
    # 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
    steps:
      - name: Checkout Code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
        with:
          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: Resolve build target
        id: resolve
        run: |
          # Route the git ref to the package(s) and version to build.
          # A per-package tag builds that one package; pushes to main (and manual
          # dispatch) build all four as "dev". Python release tags are
          # toolbox-<name>-vX.Y.Z; release-please-* and any other tag are skipped.
          REF="${GITHUB_REF}"
          case "$REF" in
            refs/tags/toolbox-core-v*)       echo "packages=core"                          >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/toolbox-core-}"       >> "$GITHUB_OUTPUT" ;;
            refs/tags/toolbox-adk-v*)        echo "packages=adk"                           >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/toolbox-adk-}"        >> "$GITHUB_OUTPUT" ;;
            refs/tags/toolbox-langchain-v*)  echo "packages=langchain"                     >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/toolbox-langchain-}"  >> "$GITHUB_OUTPUT" ;;
            refs/tags/toolbox-llamaindex-v*) echo "packages=llamaindex"                    >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/toolbox-llamaindex-}" >> "$GITHUB_OUTPUT" ;;
            refs/tags/*)                     echo "packages="                              >> "$GITHUB_OUTPUT"; echo "version="                                     >> "$GITHUB_OUTPUT" ;;
            *)                               echo "packages=core adk langchain llamaindex" >> "$GITHUB_OUTPUT"; echo "version=dev"                                   >> "$GITHUB_OUTPUT" ;;
          esac

          # Deploys only run upstream (see job-level guard), so always use the
          # production domain.
          echo "BASE_URL=https://py.mcp-toolbox.dev/" >> "$GITHUB_ENV"

      - name: Build per-package docs
        if: steps.resolve.outputs.packages != ''
        run: |
          chmod +x scripts/generate-api-docs.sh
          for PKG in ${STEPS_RESOLVE_OUTPUTS_PACKAGES}; do
            ./scripts/generate-api-docs.sh "$PKG" "${STEPS_RESOLVE_OUTPUTS_VERSION}" "$BASE_URL"
          done
        env:
          STEPS_RESOLVE_OUTPUTS_PACKAGES: ${{ steps.resolve.outputs.packages }}
          STEPS_RESOLVE_OUTPUTS_VERSION: ${{ steps.resolve.outputs.version }}

      - name: Build root page
        if: steps.resolve.outputs.packages != '' && startsWith(github.ref, 'refs/tags/')
        run: |
          chmod +x scripts/generate-root.sh
          ./scripts/generate-root.sh "$BASE_URL"

      - name: Deploy to gh-pages
        if: steps.resolve.outputs.packages != ''
        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-site/public
          keep_files: true
          cname: ${{ github.repository == 'googleapis/mcp-toolbox-sdk-python' && 'py.mcp-toolbox.dev' || '' }}