docs: add Hugo/Docsy docs-site scaffold for Python API reference

.gitignore

@@ -15,3 +15,9 @@ __pycache__/**
 **/.coverage
 build/
 **/build/
+
+# Hugo docs-site build output
+node_modules/
+docs-site/public/
+docs-site/resources/
+.hugo_build.lock

docs-site/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+date = '{{ .Date }}'
+draft = true
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
++++

docs-site/assets/scss/_styles_project.scss

@@ -0,0 +1,27 @@
+@import 'td/code-dark';
+
+.td-navbar {
+  background-color: #80a7e9 !important;
+}
+
+.nav-tabs {
+  flex-wrap: nowrap;
+  white-space: nowrap;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.td-content table {
+  display: table;
+  width: 100% !important;
+  margin-bottom: 1.5rem;
+}
+
+.td-footer {
+  background-color: rgb(64, 63, 76) !important; 
+  border-top: none;
+}
+
+.td-footer, .td-footer a, .td-footer span {
+  color: #ffffff !important;
+}

docs-site/assets/scss/_variables_project.scss

@@ -0,0 +1,4 @@
+$primary: #80a7e9;
+$secondary: #4484f4;
+
+$navbar-dark-bg: $primary;

docs-site/assets/scss/main.scss

@@ -0,0 +1 @@
+@import "td/main";

docs-site/go.mod

@@ -0,0 +1,8 @@
+module github.com/googleapis/mcp-toolbox-sdk-python/docs-site
+
+go 1.24.13
+
+require (
+	github.com/google/docsy v0.14.3 // indirect
+	github.com/google/docsy/dependencies v0.7.2 // indirect
+)

docs-site/go.sum

@@ -0,0 +1,8 @@
+github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/google/docsy v0.14.3 h1:4uFgPWTPj4NT79IboVkXGi49LLQadLVfU4WNOfD/s74=
+github.com/google/docsy v0.14.3/go.mod h1:1Fj1W1O3esZh7IBQ8XAYtxtg10udBXuGI89+LUQc1AU=
+github.com/google/docsy/dependencies v0.7.2 h1:+t5ufoADQAj4XneFphz4A+UU0ICAxmNaRHVWtMYXPSI=
+github.com/google/docsy/dependencies v0.7.2/go.mod h1:gihhs5gmgeO+wuoay4FwOzob+jYJVyQbNaQOh788lD4=
+github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/twbs/bootstrap v5.3.8+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

docs-site/hugo.toml

@@ -0,0 +1,79 @@
+title = "MCP Toolbox Python API"
+
+[params]
+  offlineSearch = true
+  copyright = "Google LLC"
+
+# Hand-edited version lists, one per package. Newest first — the order is
+# mirrored into the dropdown. Add a block before tagging a release, and only
+# list versions whose /<pkg>/<version>/ docs already exist (or will after the
+# backfill run), or the dropdown link 404s. URLs are root-relative so they
+# resolve against whatever host serves the page (production or staging).
+[params.versions]
+  [[params.versions.core]]
+    version = "dev"
+    url = "/core/dev/"
+  [[params.versions.adk]]
+    version = "dev"
+    url = "/adk/dev/"
+  [[params.versions.langchain]]
+    version = "dev"
+    url = "/langchain/dev/"
+  [[params.versions.llamaindex]]
+    version = "dev"
+    url = "/llamaindex/dev/"
+
+[markup.goldmark.renderer]
+  unsafe = true
+
+# Resolve relative .md / _index.md links to per-version pretty URLs. Kept as a
+# safety net for any cross-links pydoc-markdown's crossref processor emits so
+# none leak as raw .md hrefs once fed through Hugo.
+[markup.goldmark.renderHooks.link]
+  useEmbedded = "fallback"
+
+[markup.highlight]
+  noClasses = false
+  style = "tango"
+
+[params.ui]
+  navbar_logo = true
+  sidebar_menu_foldable = true
+  ul_show = 2
+  breadcrumb_disable = true
+  sidebar_menu_compact = false
+  showLightDarkModeMenu = true
+
+[[menu.main]]
+  name = "Documentation"
+  url = "https://mcp-toolbox.dev"
+  weight = 10
+
+[[menu.main]]
+  name = "GitHub"
+  url = "https://github.com/googleapis/mcp-toolbox-sdk-python"
+  weight = 20
+  pre = "<i class='fab fa-github'></i>"
+
+[outputFormats]
+  # Dropdown fragment, fetched at runtime by the navbar version selector so
+  # frozen old version pages show newly-added versions without a rebuild.
+  [outputFormats.releases]
+    baseName = "releases"
+    isPlainText = true
+    mediaType = "text/releases"
+  # Per-package "latest" redirect, hoisted to /<pkg>/latest/index.html.
+  [outputFormats.latest]
+    baseName = "latest"
+    mediaType = "text/html"
+    isHTML = true
+
+[mediaTypes."text/releases"]
+  suffixes = ["releases"]
+
+[outputs]
+  home = ["HTML", "JSON", "releases", "latest"]   # JSON kept for offline search
+
+[module]
+  [[module.imports]]
+    path = "github.com/google/docsy"

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

@@ -0,0 +1,11 @@
+{{- $pkg := .Site.Params.package | default "" -}}
+{{- $target := printf "/%s/dev/" $pkg -}}
+{{- with index .Site.Params.versions $pkg }}
+  {{- range . }}{{ if ne .version "dev" }}{{ $target = .url }}{{ break }}{{ end }}{{ end }}
+{{- end -}}
+<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<meta http-equiv="refresh" content="0; url={{ $target }}">
+<link rel="canonical" href="{{ $target }}">
+</head><body><a href="{{ $target }}">Redirecting…</a>
+<script>location.replace('{{ $target }}');</script></body></html>

docs-site/layouts/_default/home.releases.releases

@@ -0,0 +1,7 @@
+{{- $pkg := .Site.Params.package | default "" -}}
+<a class="dropdown-item" href="/{{ $pkg }}/latest/">latest</a>
+{{- with index .Site.Params.versions $pkg }}
+  {{- range . }}
+<a class="dropdown-item" href="{{ .url }}">{{ .version }}</a>
+  {{- end }}
+{{- end -}}

docs-site/layouts/_partials/hooks/head-end.html

@@ -0,0 +1 @@
+<script src='{{ "js/w3.js" | relURL }}'></script>

docs-site/layouts/_partials/navbar-version-selector.html

@@ -0,0 +1,16 @@
+{{/* Require a package context: on the rootless landing $pkg is empty, which
+     would emit a broken //releases.releases include and a meaningless picker. */ -}}
+{{ if and .Site.Params.versions .Site.Params.package -}}
+{{ $pkg := .Site.Params.package | default "" -}}
+<div class="dropdown">
+  <a class="nav-link dropdown-toggle" href="#" role="button"
+     data-bs-toggle="dropdown" aria-expanded="false">
+    {{ .Site.Params.version | default "Versions" }}
+  </a>
+  <div class="dropdown-menu"
+       w3-include-html="/{{ $pkg }}/releases.releases"
+       w3-include-html-default='<a class="dropdown-item" href="/{{ $pkg }}/dev/">dev</a>'>
+  </div>
+  <script>w3.includeHTML();</script>
+</div>
+{{ end -}}

docs-site/layouts/_partials/sidebar-tree.html

@@ -0,0 +1,205 @@
+{{ $context := .context -}}
+{{ $sidebarRoot := .sidebarRoot -}}
+{{ $sidebarRootID := .sidebarRootID -}}
+{{ $cacheSidebar := .cacheSidebar -}}
+
+{{ with $context -}}
+
+{{/* When the sidebar is cached, "active" class is set client side. */ -}}
+{{ $shouldDelayActive := $cacheSidebar -}}
+
+<div id="td-sidebar-menu" class="td-sidebar__inner{{ if $shouldDelayActive }} d-none{{ end }}">
+  {{ if not .Site.Params.ui.sidebar_search_disable -}}
+
+  <form class="td-sidebar__search d-flex align-items-center">
+    {{ partial "search-input.html" . }}
+    <button class="btn btn-link td-sidebar__toggle" type="button" {{/**/ -}}
+      data-bs-toggle="collapse" data-bs-target="#td-section-nav" {{/**/ -}}
+      aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    </button>
+  </form>
+
+  {{- else -}}
+
+  <div id="content-mobile">
+  <form class="td-sidebar__search d-flex align-items-center">
+    {{ partial "search-input.html" . }}
+    <button class="btn btn-link td-sidebar__toggle" type="button" {{/**/ -}}
+      data-bs-toggle="collapse" data-bs-target="#td-section-nav" {{/**/ -}}
+      aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    </button>
+  </form>
+  </div>
+  <div id="content-desktop"></div>
+
+  {{- end }}
+  {{/* */ -}}
+
+  <nav class="td-sidebar-nav collapse
+        {{- if .Site.Params.ui.sidebar_search_disable }} td-sidebar-nav--search-disabled{{ end -}}
+        {{- if .Site.Params.ui.sidebar_menu_foldable }} foldable-nav{{ end }}" {{/**/ -}}
+      id="td-section-nav"
+      {{- if .Site.Params.ui.sidebar_root_enabled }} data-sidebar-root-id="{{ $sidebarRootID }}"{{ end -}}
+    >
+    {{ if and .Site.Params.ui.sidebar_lang_menu (gt (len .Site.Home.Translations) 0) -}}
+    <div class="td-sidebar-nav__section nav-item d-block d-lg-none">
+      {{ partial "navbar-lang-selector.html" . }}
+    </div>
+    {{ end -}}
+    {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}}
+    {{ if $sidebarRoot -}}
+      {{ $navRoot = $sidebarRoot -}}
+    {{ end -}}
+    {{ $ulNr := 0 -}}
+    {{ $ulShow := .Site.Params.ui.ul_show | default 1 -}}
+    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 100 -}}
+    <ul class="td-sidebar-nav__section pe-md-3 ul-{{ $ulNr }}">
+      {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1)) }}
+    </ul>
+    {{/* Cross-package links: literal hrefs (not menu/relref), so they resolve
+         verbatim from any per-package subdirectory baseURL without relURL
+         rewriting them into broken /core/dev/core/latest/ style paths. Placed
+         after the page's own tree so the current page's heading comes first. */ -}}
+    {{ $pkg := .Site.Params.package | default "" -}}
+    <ul class="td-sidebar-nav__section pe-md-3 ul-0">
+      <li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child">
+        <a class="align-left ps-0 td-sidebar-link td-sidebar-link__section{{ if eq $pkg "core" }} active{{ end }}" href="/core/latest/"><span{{ if eq $pkg "core" }} class="td-sidebar-nav-active-item"{{ end }}>Core</span></a>
+      </li>
+      <li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child">
+        <a class="align-left ps-0 td-sidebar-link td-sidebar-link__section{{ if eq $pkg "adk" }} active{{ end }}" href="/adk/latest/"><span{{ if eq $pkg "adk" }} class="td-sidebar-nav-active-item"{{ end }}>ADK</span></a>
+      </li>
+      <li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child">
+        <a class="align-left ps-0 td-sidebar-link td-sidebar-link__section{{ if eq $pkg "langchain" }} active{{ end }}" href="/langchain/latest/"><span{{ if eq $pkg "langchain" }} class="td-sidebar-nav-active-item"{{ end }}>LangChain</span></a>
+      </li>
+      <li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child">
+        <a class="align-left ps-0 td-sidebar-link td-sidebar-link__section{{ if eq $pkg "llamaindex" }} active{{ end }}" href="/llamaindex/latest/"><span{{ if eq $pkg "llamaindex" }} class="td-sidebar-nav-active-item"{{ end }}>LlamaIndex</span></a>
+      </li>
+    </ul>
+  </nav>
+</div>
+
+{{- end }}{{/* with $context */ -}}
+
+{{ define "section-tree-nav-section" -}}
+  {{/* cSpell:ignore manuallink manuallinkrelref manuallinktitle */ -}}
+  {{ $s := .section -}}
+  {{ $p := .page -}}
+  {{ $shouldDelayActive := .shouldDelayActive -}}
+  {{ $sidebarMenuTruncate := .sidebarMenuTruncate -}}
+  {{ $treeRoot := cond (eq .ulNr 0) true false -}}
+  {{ $ulNr := .ulNr -}}
+  {{ $ulShow := .ulShow -}}
+  {{ $active := and (not $shouldDelayActive) (eq $s $p) -}}
+  {{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}}
+  {{ $show := cond
+        (or
+          (lt $ulNr $ulShow)
+          $activePath
+          (and (not $shouldDelayActive) (eq $s.Parent $p.Parent))
+          (and (not $shouldDelayActive) (eq $s.Parent $p))
+          (not $p.Site.Params.ui.sidebar_menu_compact)
+          (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))
+        )
+        true false
+  -}}
+  {{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
+  {{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
+  {{ $pages := $pages_tmp | first $sidebarMenuTruncate -}}
+  {{ $truncatedEntryCount := sub (len $pages_tmp) $sidebarMenuTruncate -}}
+
+  {{ if gt $truncatedEntryCount 0 -}}
+    {{ warnf "WARNING: %d sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least %d (from %d) in your config file. Section: %s"
+        $truncatedEntryCount (len $pages_tmp) $sidebarMenuTruncate  $s.Path -}}
+  {{ end -}}
+
+  {{ $withChild := gt (len $pages) 0 -}}
+  {{ $manualLink :=
+      cond
+        (isset $s.Params "manuallink")
+        $s.Params.manualLink
+        (cond
+          (isset $s.Params "manuallinkrelref")
+          (relref $s $s.Params.manualLinkRelref)
+          $s.RelPermalink
+        )
+  -}}
+  {{ $manualLinkTitle :=
+      cond
+        (isset $s.Params "manuallinktitle")
+        $s.Params.manualLinkTitle
+        $s.Title
+  -}}
+  {{ if and $treeRoot (eq $s.Params.sidebar_root_for "self") -}}
+    {{ with $s.Parent -}}
+      {{ $manualLink = .RelPermalink -}}
+    {{ end -}}
+  {{ end -}}
+  <li class="td-sidebar-nav__section-title td-sidebar-nav__section
+        {{- if $withChild }} with-child{{ else }} without-child{{ end -}}
+        {{ if $activePath }} active-path{{ end -}}
+        {{ if (not (or $show $p.Site.Params.ui.sidebar_menu_foldable )) }} collapse{{ end -}}
+      " {{/**/ -}}
+      id="{{ $mid }}-li" {{- /**/ -}}
+    >
+    {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}
+    <input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
+    <label for="{{ $mid }}-check">{{/**/ -}}
+      <a href="{{ $manualLink }}"
+        {{- if ne $s.LinkTitle $manualLinkTitle }} {{/**/ -}}
+          title="{{ $manualLinkTitle }}"
+        {{- end -}}
+        {{ with $s.Params.manualLinkTarget }} {{/**/ -}}
+          target="{{ . }}"
+          {{- if eq . "_blank" }} rel="noopener"{{ end -}}
+        {{ end }} {{/**/ -}}
+        class="align-left ps-0 {{ if $active}} active{{ end }} td-sidebar-link
+          {{- if $s.IsPage }} td-sidebar-link__page
+          {{- else }} td-sidebar-link__section
+          {{- end }}
+          {{- if $treeRoot }} tree-root{{ end }}" {{/**/ -}}
+        id="{{ $mid }}" {{- /**/ -}}
+      >
+        {{- with $s.Params.Icon -}}
+          <i class="{{ . }}"></i>
+        {{- end -}}
+        <span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">
+          {{- $s.LinkTitle -}}
+        </span> {{- /**/ -}}
+      </a> {{- /**/ -}}
+    </label>
+    {{ else -}}
+      <a href="{{ $manualLink }}"
+        {{- if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end -}}
+        {{ with $s.Params.manualLinkTarget }} {{/**/ -}}
+          target="{{ . }}"
+          {{- if eq . "_blank" }} rel="noopener"{{ end -}}
+        {{ end }} {{/**/ -}}
+        class="align-left ps-0
+          {{- if $active}} active{{ end }} {{/**/ -}}
+          td-sidebar-link
+          {{- if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}
+          {{- if $treeRoot }} tree-root{{ end }}" {{/**/ -}}
+        id="{{ $mid }}" {{- /**/ -}}
+      >
+      {{- with $s.Params.Icon -}}
+        <i class="{{ . }}"></i>
+      {{- end -}}
+      <span class="
+        {{- if $active }}td-sidebar-nav-active-item{{ end -}}
+        {{- if and $treeRoot $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
+      ">
+        {{- $s.LinkTitle -}}
+      </span></a>
+    {{- end -}}
+    {{ if $withChild -}}
+    {{ $ulNr := add $ulNr 1 }}
+    <ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
+      {{ range $pages -}}
+        {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}}
+          {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }}
+        {{- end }}
+      {{- end }}
+    </ul>
+    {{- end }}
+  </li>
+{{- end -}}