docs: add api-docs GitHub workflow for Python API reference

.github/workflows/api-docs.yml

@@ -0,0 +1,111 @@
+# 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
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        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
+
+      - 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' || '' }}

docs-site/hugo.toml

@@ -13,15 +13,51 @@ title = "MCP Toolbox Python API"
   [[params.versions.core]]
     version = "dev"
     url = "/core/dev/"
+  [[params.versions.core]]
+    version = "v1.1.0"
+    url = "/core/v1.1.0/"
+  [[params.versions.core]]
+    version = "v1.0.0"
+    url = "/core/v1.0.0/"
+  [[params.versions.core]]
+    version = "v0.6.0"
+    url = "/core/v0.6.0/"
   [[params.versions.adk]]
     version = "dev"
     url = "/adk/dev/"
+  [[params.versions.adk]]
+    version = "v1.0.1"
+    url = "/adk/v1.0.1/"
+  [[params.versions.adk]]
+    version = "v1.0.0"
+    url = "/adk/v1.0.0/"
+  [[params.versions.adk]]
+    version = "v0.7.0"
+    url = "/adk/v0.7.0/"
   [[params.versions.langchain]]
     version = "dev"
     url = "/langchain/dev/"
+  [[params.versions.langchain]]
+    version = "v1.0.1"
+    url = "/langchain/v1.0.1/"
+  [[params.versions.langchain]]
+    version = "v1.0.0"
+    url = "/langchain/v1.0.0/"
+  [[params.versions.langchain]]
+    version = "v0.6.0"
+    url = "/langchain/v0.6.0/"
   [[params.versions.llamaindex]]
     version = "dev"
     url = "/llamaindex/dev/"
+  [[params.versions.llamaindex]]
+    version = "v1.0.0"
+    url = "/llamaindex/v1.0.0/"
+  [[params.versions.llamaindex]]
+    version = "v0.7.0"
+    url = "/llamaindex/v0.7.0/"
+  [[params.versions.llamaindex]]
+    version = "v0.6.0"
+    url = "/llamaindex/v0.6.0/"
 
 [markup.goldmark.renderer]
   unsafe = true