ci(api-docs): isolate per-package builds and stabilize root URL

.github/workflows/api-docs.yml

@@ -16,12 +16,18 @@
 name: "API Reference Deployment"
 on:
   push:
-    branches: [ 'main', 'ref-docs' ]
+    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
@@ -48,32 +54,41 @@ jobs:
           cd docs-site
           npm install postcss postcss-cli autoprefixer
 
-      - name: Build API Reference
+      - 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
-
-          # If the Action is running in the official upstream repository, 
-          # strictly route all assets and links to the production custom domain.
-          if [[ "${{ github.repository }}" == "googleapis/mcp-toolbox-sdk-go" ]]; then
-            BASE_URL="https://go.mcp-toolbox.dev/"
-
-          # If the Action is running in an external contributor's fork, 
-          # dynamically fallback to their personal GitHub Pages URL.
-          # This ensures external contributors can successfully build and preview 
-          # docsite changes on their own forks without encountering broken links.
-          else
-            BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
-          fi
-
-          if [[ $GITHUB_REF == refs/tags/* ]]; then
-            VERSION=${GITHUB_REF#refs/tags/}
-          else
-            VERSION="main"
-          fi
-
-          ./scripts/generate-api-docs.sh "$VERSION" "$BASE_URL"
+          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@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

docs-site/hugo.toml

@@ -1,4 +1,3 @@
-baseURL = "PLACEHOLDER_BASE_URL"
 title = "MCP Toolbox Go API"
 
 [params]

scripts/generate-api-docs.sh

@@ -1,87 +1,42 @@
 #!/bin/bash
-set -e
+set -euo pipefail
 
-export PATH=$PATH:$(go env GOPATH)/bin
+export PATH="$PATH:$(go env GOPATH)/bin"
 
-VERSION=${1:-"main"}
-BASE_URL=${2:-"/"}
+PACKAGE="${1:?package required (core|tbadk|tbgenkit)}"
+VERSION="${2:?version required (e.g. v1.0.0 or dev)}"
+BASE_URL="${3:-/}"
 
-go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
-
-rm -rf docs-site/content/*
-mkdir -p docs-site/content/docs
+case "$PACKAGE" in
+  core)     TITLE="Core" ;;
+  tbadk)    TITLE="Tbadk" ;;
+  tbgenkit) TITLE="Tbgenkit" ;;
+  *)        echo "Unknown package: $PACKAGE" >&2; exit 1 ;;
+esac
 
-cat <<EOF > docs-site/content/_index.md
----
-title: "MCP Toolbox Go SDK"
-type: docs
----
-
-EOF
+go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
 
-cat README.md >> docs-site/content/_index.md
+# Per-build content tree in a temp dir, kept out of the checked-in
+# docs-site/content so concurrent package builds never trample each other.
+# The package's API reference is the home page, so /<pkg>/<version>/ lands
+# directly on the docs (the repo README lives only at the site root).
+CONTENT_DIR="$(mktemp -d)"
+trap 'rm -rf "$CONTENT_DIR"' EXIT
 
-cat <<EOF > docs-site/content/docs/_index.md
+cat > "$CONTENT_DIR/_index.md" <<EOF
 ---
-title: "Packages"
+title: "MCP Toolbox Go SDK — ${TITLE} (${VERSION})"
 type: docs
-weight: 1
-alwaysopen: true
 ---
-Select a framework to view its public variables, functions, and structs.
-EOF
 
-generate_package() {
-  local PKG_DIR=$1
-  local TITLE=$2
-  local WEIGHT=$3
-  local MANUAL_VERSIONS=$4
-  local MD_FILE="docs-site/content/docs/${PKG_DIR}.md"
+Viewing \`${VERSION}\`.
 
-  printf -- "---\ntitle: \"%s\"\ntype: docs\nweight: %s\n---\n\n" "$TITLE" "$WEIGHT" > "$MD_FILE"
-
-  cat <<EOF >> "$MD_FILE"
-<div style="margin-bottom: 2rem; padding: 1rem; background-color: #f8f9fa; border-radius: 8px; border: 1px solid #e9ecef; display: inline-block;">
-  <label for="${PKG_DIR}-version" style="font-weight: bold; margin-right: 10px; color: #4a4a4a;">Package Version:</label>
-
-  <select id="${PKG_DIR}-version" onchange="if (this.value) window.location.href=this.value;" style="padding: 5px 10px; border-radius: 4px; border: 1px solid #ccc; background-color: white; color: #333333; cursor: pointer;">
-    <option value="${BASE_URL}main/docs/${PKG_DIR}/">main (latest)</option>
 EOF
-
-  for VER in $MANUAL_VERSIONS; do
-    echo "    <option value=\"${BASE_URL}${VER}/docs/${PKG_DIR}/\">${VER}</option>" >> "$MD_FILE"
-  done
-
-  cat <<EOF >> "$MD_FILE"
-  </select>
-</div>
-EOF
-
-  gomarkdoc ./${PKG_DIR}/... | sed '/^# /d' >> "$MD_FILE"
-}
-
-# --- EXECUTE GENERATOR (UPDATE THESE BEFORE RELEASING!) ---
-# To add a version to the dropdown, just type it inside the quotes separated by a space.
-# Example: generate_package "core" "Core" "10" "v1.0.0 v0.9.0"
-
-generate_package "core" "Core" "10" ""
-generate_package "tbadk" "Tbadk" "20" ""
-generate_package "tbgenkit" "Tbgenkit" "30" ""
+gomarkdoc "./${PACKAGE}/..." | sed '/^# /d' >> "$CONTENT_DIR/_index.md"
 
 cd docs-site
-sed -i "s|PLACEHOLDER_BASE_URL|${BASE_URL}|g" hugo.toml
-
-HUGO_PARAMS_VERSION="${VERSION}" hugo --minify --baseURL "${BASE_URL}${VERSION}/" --destination "public/${VERSION}"
-
-cat <<EOF > public/index.html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta http-equiv="refresh" content="0; url=${BASE_URL}${VERSION}/" />
-</head>
-<body style="background-color: rgb(64, 63, 76); color: white; text-align: center; padding-top: 50px; font-family: sans-serif;">
-  <p>Redirecting to the latest API version (${VERSION})...</p>
-  <script>window.location.replace('${BASE_URL}${VERSION}/');</script>
-</body>
-</html>
-EOF
+HUGO_PARAMS_VERSION="${VERSION}" hugo \
+  --minify \
+  --contentDir "${CONTENT_DIR}" \
+  --baseURL "${BASE_URL}${PACKAGE}/${VERSION}/" \
+  --destination "public/${PACKAGE}/${VERSION}"

scripts/generate-root.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -euo pipefail
+
+BASE_URL="${1:-/}"
+
+# Render the repo README (from the checked-out tag) as the root landing page.
+# Built only on tag pushes so the root URL tracks the latest release and stays
+# stable between main-branch dev builds.
+CONTENT_DIR="$(mktemp -d)"
+trap 'rm -rf "$CONTENT_DIR"' EXIT
+
+cat > "$CONTENT_DIR/_index.md" <<EOF
+---
+title: "MCP Toolbox Go SDK"
+type: docs
+---
+EOF
+cat README.md >> "$CONTENT_DIR/_index.md"
+
+cd docs-site
+hugo \
+  --minify \
+  --contentDir "${CONTENT_DIR}" \
+  --baseURL "${BASE_URL}" \
+  --destination "public"