docs: document the API reference docs pipeline in DEVELOPER.md#697
Merged
Conversation
Copies the Hugo/Docsy site scaffold from the JS SDK repo (googleapis/mcp-toolbox-sdk-js, docs-site/) byte-for-byte. No Python-specific changes in this commit — retargeting is done in the follow-up commit so the diff against the known-good JS pipeline is reviewable in isolation. Files copied unchanged: archetypes, assets (scss + icon), layouts (home.latest, home.releases, head-end hook, navbar-version-selector, sidebar-tree), static (w3.js + favicons), go.mod, go.sum, hugo.toml, package.json (postcss deps).
Applies the Python-specific edits on top of the verbatim JS copy. Every change is listed so it can be diffed against the JS pipeline: - hugo.toml: title -> MCP Toolbox Python API; [params.versions] rewritten to the four Python packages (core, adk, langchain, llamaindex), dev only; GitHub menu link -> the Python repo; [markup.goldmark.renderHooks.link] useEmbedded = fallback kept as a safety net for any relative .md links from pydoc-markdown's crossref processor. - go.mod: module path -> .../mcp-toolbox-sdk-python/docs-site (docsy still pinned v0.14.3, matching Go/JS). - sidebar-tree.html: cross-package links core/adk -> core/adk/langchain/llamaindex. - .gitignore: ignore Hugo build output (public/, resources/, .hugo_build.lock, node_modules/) and docs-site/package-lock.json. Verified: hugo v0.152.2 extended builds the scaffold clean (Docsy main.css compiles via PostCSS/autoprefixer); only the harmless no-layout-for-json home warning remains.
The PostCSS toolchain (autoprefixer/postcss/postcss-cli) was installed with npm install, which re-resolves the latest matching semver on every run. A broken upstream patch (e.g. browserslist 4.28.3) could then fail both the deploy and backfill workflows nondeterministically. Commit the lockfile so npm ci can install the exact, vetted versions instead.
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.
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 backfill build.
Add an API Reference Documentation section to the existing DEVELOPER.md covering the deploy workflow, version picker, backfill workflow (with preview), and local builds.
twishabansal
added
the
do not merge
anubhav756
approved these changes
Jun 24, 2026
The API reference's documented surface is the curated MODULES in generate-api-docs.sh; explain that single source of truth and the steps (script case arm, api-docs.yml tag router + default build list, hugo.toml version picker) to onboard a new package.
twishabansal
removed
the
do not merge
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an API Reference Documentation section to the existing root
DEVELOPER.md, documenting the docs feature (pydoc-markdown → Hugo/Docsy → gh-pages). Mirrors JS #388, adapted for Python.