docs: add Hugo/Docsy docs-site scaffold for Python API reference#688
Open
twishabansal wants to merge 3 commits into
Open
docs: add Hugo/Docsy docs-site scaffold for Python API reference#688twishabansal wants to merge 3 commits into
twishabansal wants to merge 3 commits into
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.
This was referenced Jun 22, 2026
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.
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
First PR in the API reference docs pipeline for the Python SDK, mirroring the Go and JS SDK pipelines (
go.mcp-toolbox.dev,js.mcp-toolbox.dev). This PR adds only the Hugo/Docsy site scaffold underdocs-site/, serving frompy.mcp-toolbox.dev.Commits are split so copy and edit never mix. Commit 1 copies the scaffold directly from the JS SDK repo. The follow-up commit performs the Python-specific edits, so the diff against the known-good JS pipeline is reviewable in isolation.
Deviation from Go (intentional, same as JS)
docs-site/package.jsonis tracked here, whereas the Go repo installs postcss ad hoc and doesn't track it — sopostcss/postcss-cli/autoprefixerare pinned andnpm install --no-workspaceslands them indocs-site/node_modules(where Hugo's PostCSS looks). Unlike JS, the Python repo root is not an npm workspace, so there is no hoisting concern;--no-workspacesis harmless and kept for parity with the JS workflow.Testing
Builds clean on the pinned toolchain (Hugo 0.152.2 extended + Docsy v0.14.3):
cd docs-site npm install --no-workspaces hugo --minifyExits 0,
public/produced, no Docsy/module errors (only the harmless no-layout-for-json home warning, which resolves once content pages exist).