From 7d4ff0aec2742f226926874f805e71a65f6ded1e Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Mon, 22 Jun 2026 14:13:38 +0530 Subject: [PATCH 1/4] docs: copy api-docs workflow verbatim from Go SDK --- .github/workflows/api-docs.yml | 97 ++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 .github/workflows/api-docs.yml diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml new file mode 100644 index 000000000..aee6d27c9 --- /dev/null +++ b/.github/workflows/api-docs.yml @@ -0,0 +1,97 @@ +# 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-go' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout Code + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + submodules: recursive + fetch-depth: 0 + + - name: Set up Go + uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6 + with: + go-version: '1.25.0' + + - name: Setup Hugo + uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3 + with: + hugo-version: '0.152.2' + extended: true + + - name: Install PostCSS Dependencies + run: | + cd docs-site + npm install postcss postcss-cli autoprefixer + + - 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 three as "dev". Any other tag is skipped. + REF="${GITHUB_REF}" + case "$REF" in + refs/tags/core/v*) echo "packages=core" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/core/}" >> "$GITHUB_OUTPUT" ;; + refs/tags/tbadk/v*) echo "packages=tbadk" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbadk/}" >> "$GITHUB_OUTPUT" ;; + refs/tags/tbgenkit/v*) echo "packages=tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbgenkit/}" >> "$GITHUB_OUTPUT" ;; + refs/tags/*) echo "packages=" >> "$GITHUB_OUTPUT"; echo "version=" >> "$GITHUB_OUTPUT" ;; + *) echo "packages=core tbadk tbgenkit" >> "$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://go.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-go' && 'go.mcp-toolbox.dev' || '' }} From 1f26da021d7d1ef8a79a999e98f5056b86074850 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Mon, 22 Jun 2026 14:16:06 +0530 Subject: [PATCH 2/4] docs: retarget api-docs workflow for the Python SDK --- .github/workflows/api-docs.yml | 46 +++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml index aee6d27c9..8f1965214 100644 --- a/.github/workflows/api-docs.yml +++ b/.github/workflows/api-docs.yml @@ -27,51 +27,63 @@ concurrency: jobs: deploy: # Never run on forks; docs deploy only from the upstream repository. - if: github.repository == 'googleapis/mcp-toolbox-sdk-go' + if: github.repository == 'googleapis/mcp-toolbox-sdk-python' runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout Code - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 with: submodules: recursive fetch-depth: 0 - - name: Set up Go - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6 + - name: Set up Python + uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6 with: - go-version: '1.25.0' + 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 - + extended: true + - name: Install PostCSS Dependencies run: | + # --no-workspaces installs into docs-site/node_modules (where Hugo's + # PostCSS looks). docs-site/package.json pins postcss/postcss-cli/ + # autoprefixer. cd docs-site - npm install postcss postcss-cli autoprefixer + npm install --no-workspaces - 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 three as "dev". Any other tag is skipped. + # dispatch) build all four as "dev". Python release tags are + # toolbox--vX.Y.Z; release-please-* and any other tag are skipped. REF="${GITHUB_REF}" case "$REF" in - refs/tags/core/v*) echo "packages=core" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/core/}" >> "$GITHUB_OUTPUT" ;; - refs/tags/tbadk/v*) echo "packages=tbadk" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbadk/}" >> "$GITHUB_OUTPUT" ;; - refs/tags/tbgenkit/v*) echo "packages=tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=${REF#refs/tags/tbgenkit/}" >> "$GITHUB_OUTPUT" ;; - refs/tags/*) echo "packages=" >> "$GITHUB_OUTPUT"; echo "version=" >> "$GITHUB_OUTPUT" ;; - *) echo "packages=core tbadk tbgenkit" >> "$GITHUB_OUTPUT"; echo "version=dev" >> "$GITHUB_OUTPUT" ;; + 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://go.mcp-toolbox.dev/" >> "$GITHUB_ENV" + echo "BASE_URL=https://py.mcp-toolbox.dev/" >> "$GITHUB_ENV" - name: Build per-package docs if: steps.resolve.outputs.packages != '' @@ -93,5 +105,5 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs-site/public - keep_files: true - cname: ${{ github.repository == 'googleapis/mcp-toolbox-sdk-go' && 'go.mcp-toolbox.dev' || '' }} + keep_files: true + cname: ${{ github.repository == 'googleapis/mcp-toolbox-sdk-python' && 'py.mcp-toolbox.dev' || '' }} From 44e7b1f557b31ea0a7895931b69d4e45cfec7d6d Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Mon, 22 Jun 2026 14:16:50 +0530 Subject: [PATCH 3/4] docs: seed released versions in the version selector --- docs-site/hugo.toml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs-site/hugo.toml b/docs-site/hugo.toml index 75eb2fac8..a6ec3cd5f 100644 --- a/docs-site/hugo.toml +++ b/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 From 9f035a9be2c381d0a367268c5e2a132593b6996d Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Mon, 22 Jun 2026 16:33:52 +0530 Subject: [PATCH 4/4] ci(docs): install PostCSS deps with npm ci for reproducible builds Use npm ci against the committed docs-site lockfile instead of npm install, which re-resolved latest semver each run and could pull a broken upstream patch into the deploy build. --- .github/workflows/api-docs.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml index 8f1965214..4c9601938 100644 --- a/.github/workflows/api-docs.yml +++ b/.github/workflows/api-docs.yml @@ -58,11 +58,13 @@ jobs: - name: Install PostCSS Dependencies run: | - # --no-workspaces installs into docs-site/node_modules (where Hugo's - # PostCSS looks). docs-site/package.json pins postcss/postcss-cli/ - # autoprefixer. + # 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 install --no-workspaces + npm ci - name: Resolve build target id: resolve