Skip to content

Commit 61e09d1

Browse files
twishabansaltwishabansal
authored
docs: add Hugo/Docsy docs-site scaffold for Python API reference (#688)
* docs: copy docs-site scaffold verbatim from JS SDK 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). * docs: retarget docs-site scaffold for the Python SDK 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. * build(docs): commit docs-site lockfile for reproducible installs 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.
1 parent 85ca73b commit 61e09d1

23 files changed

Lines changed: 1283 additions & 0 deletions

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,9 @@ __pycache__/**
1515
**/.coverage
1616
build/
1717
**/build/
18+
19+
# Hugo docs-site build output
20+
node_modules/
21+
docs-site/public/
22+
docs-site/resources/
23+
.hugo_build.lock

‎docs-site/archetypes/default.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
date = '{{ .Date }}'
3+
draft = true
4+
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
5+
+++

‎docs-site/assets/icons/logo.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs-site/assets/scss/_styles_project.scss‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
@import 'td/code-dark';
2+
3+
.td-navbar {
4+
background-color: #80a7e9 !important;
5+
}
6+
7+
.nav-tabs {
8+
flex-wrap: nowrap;
9+
white-space: nowrap;
10+
overflow-x: auto;
11+
overflow-y: hidden;
12+
}
13+
14+
.td-content table {
15+
display: table;
16+
width: 100% !important;
17+
margin-bottom: 1.5rem;
18+
}
19+
20+
.td-footer {
21+
background-color: rgb(64, 63, 76) !important;
22+
border-top: none;
23+
}
24+
25+
.td-footer, .td-footer a, .td-footer span {
26+
color: #ffffff !important;
27+
}

‎docs-site/assets/scss/_variables_project.scss‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
$primary: #80a7e9;
2+
$secondary: #4484f4;
3+
4+
$navbar-dark-bg: $primary;

‎docs-site/assets/scss/main.scss‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@import "td/main";

‎docs-site/go.mod‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
module github.com/googleapis/mcp-toolbox-sdk-python/docs-site
2+
3+
go 1.24.13
4+
5+
require (
6+
github.com/google/docsy v0.14.3 // indirect
7+
github.com/google/docsy/dependencies v0.7.2 // indirect
8+
)

‎docs-site/go.sum‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
2+
github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
3+
github.com/google/docsy v0.14.3 h1:4uFgPWTPj4NT79IboVkXGi49LLQadLVfU4WNOfD/s74=
4+
github.com/google/docsy v0.14.3/go.mod h1:1Fj1W1O3esZh7IBQ8XAYtxtg10udBXuGI89+LUQc1AU=
5+
github.com/google/docsy/dependencies v0.7.2 h1:+t5ufoADQAj4XneFphz4A+UU0ICAxmNaRHVWtMYXPSI=
6+
github.com/google/docsy/dependencies v0.7.2/go.mod h1:gihhs5gmgeO+wuoay4FwOzob+jYJVyQbNaQOh788lD4=
7+
github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
8+
github.com/twbs/bootstrap v5.3.8+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

‎docs-site/hugo.toml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
title = "MCP Toolbox Python API"
2+
3+
[params]
4+
offlineSearch = true
5+
copyright = "Google LLC"
6+
7+
# Hand-edited version lists, one per package. Newest first — the order is
8+
# mirrored into the dropdown. Add a block before tagging a release, and only
9+
# list versions whose /<pkg>/<version>/ docs already exist (or will after the
10+
# backfill run), or the dropdown link 404s. URLs are root-relative so they
11+
# resolve against whatever host serves the page (production or staging).
12+
[params.versions]
13+
[[params.versions.core]]
14+
version = "dev"
15+
url = "/core/dev/"
16+
[[params.versions.adk]]
17+
version = "dev"
18+
url = "/adk/dev/"
19+
[[params.versions.langchain]]
20+
version = "dev"
21+
url = "/langchain/dev/"
22+
[[params.versions.llamaindex]]
23+
version = "dev"
24+
url = "/llamaindex/dev/"
25+
26+
[markup.goldmark.renderer]
27+
unsafe = true
28+
29+
# Resolve relative .md / _index.md links to per-version pretty URLs. Kept as a
30+
# safety net for any cross-links pydoc-markdown's crossref processor emits so
31+
# none leak as raw .md hrefs once fed through Hugo.
32+
[markup.goldmark.renderHooks.link]
33+
useEmbedded = "fallback"
34+
35+
[markup.highlight]
36+
noClasses = false
37+
style = "tango"
38+
39+
[params.ui]
40+
navbar_logo = true
41+
sidebar_menu_foldable = true
42+
ul_show = 2
43+
breadcrumb_disable = true
44+
sidebar_menu_compact = false
45+
showLightDarkModeMenu = true
46+
47+
[[menu.main]]
48+
name = "Documentation"
49+
url = "https://mcp-toolbox.dev"
50+
weight = 10
51+
52+
[[menu.main]]
53+
name = "GitHub"
54+
url = "https://github.com/googleapis/mcp-toolbox-sdk-python"
55+
weight = 20
56+
pre = "<i class='fab fa-github'></i>"
57+
58+
[outputFormats]
59+
# Dropdown fragment, fetched at runtime by the navbar version selector so
60+
# frozen old version pages show newly-added versions without a rebuild.
61+
[outputFormats.releases]
62+
baseName = "releases"
63+
isPlainText = true
64+
mediaType = "text/releases"
65+
# Per-package "latest" redirect, hoisted to /<pkg>/latest/index.html.
66+
[outputFormats.latest]
67+
baseName = "latest"
68+
mediaType = "text/html"
69+
isHTML = true
70+
71+
[mediaTypes."text/releases"]
72+
suffixes = ["releases"]
73+
74+
[outputs]
75+
home = ["HTML", "JSON", "releases", "latest"] # JSON kept for offline search
76+
77+
[module]
78+
[[module.imports]]
79+
path = "github.com/google/docsy"

‎docs-site/layouts/_default/home.latest.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{- $pkg := .Site.Params.package | default "" -}}
2+
{{- $target := printf "/%s/dev/" $pkg -}}
3+
{{- with index .Site.Params.versions $pkg }}
4+
{{- range . }}{{ if ne .version "dev" }}{{ $target = .url }}{{ break }}{{ end }}{{ end }}
5+
{{- end -}}
6+
<!DOCTYPE html>
7+
<html><head><meta charset="utf-8">
8+
<meta http-equiv="refresh" content="0; url={{ $target }}">
9+
<link rel="canonical" href="{{ $target }}">
10+
</head><body><a href="{{ $target }}">Redirecting…</a>
11+
<script>location.replace('{{ $target }}');</script></body></html>

0 commit comments

Comments
 (0)