"""Generate the API reference pages and navigation.

Zensical does not run MkDocs plugins, so the work that `mkdocs-gen-files` and

`mkdocs-literate-nav` used to do at build time happens here as a plain

pre-build step: this module writes a mkdocstrings stub (`::: <module>`) for

every public module under `docs/api/` and returns the matching nested

navigation, which `scripts/docs/build_config.py` splices into the build config.

Run as a script it just (re)generates `docs/api/`; imported, `generate`

also returns the nav so the config builder can consume it.

"""

from __future__ import annotations

import shutil

from pathlib import Path

from typing import TypeAlias

import griffe

# A MkDocs/Zensical nav is a list of entries, each either `{title: url}` for a

# page or `{title: [children]}` for a section (a bare `url` string attaches

# a section index page, courtesy of the `navigation.indexes` feature).

NavItem: TypeAlias = "str | dict[str, str | list[NavItem]]"

ROOT = Path(__file__).parent.parent.parent

API_DIR = ROOT / "docs" / "api"

# `src/mcp-types` is a distribution directory, not an import package, so each

# package's dotted module path is taken relative to its own parent: deriving

# it from `src/` would emit the unimportable `mcp-types.mcp_types.*`.

PACKAGES = (ROOT / "src" / "mcp", ROOT / "src" / "mcp-types" / "mcp_types")

# Module paths that get no page, and neither does anything under them: alias

# packages that mirror another package's namespaces (`mcp.types` mirrors

# `mcp_types`), whose canonical rendering is the mirrored package's pages; and

# removed v1 import paths (`mcp.server.fastmcp`) that only raise a pointer to

# the migration guide and carry no API.

EXCLUDED = frozenset({"mcp.types", "mcp.server.fastmcp"})

_KIND_SECTIONS = {

griffe.Kind.MODULE: "Modules",

griffe.Kind.CLASS: "Classes",

griffe.Kind.FUNCTION: "Functions",

griffe.Kind.ATTRIBUTE: "Attributes",

griffe.Kind.TYPE_ALIAS: "Type aliases",

}

class _Node:

"""A module (`url`) and/or a package with child modules (`children`)."""

def __init__(self) -> None:

self.url: str | None = None

self.children: dict[str, _Node] = {}

def child(self, name: str) -> _Node:

return self.children.setdefault(name, _Node())

def to_nav(self, title: str) -> NavItem:

if not self.children:

assert self.url is not None

return {title: self.url}

items: list[NavItem] = []

if self.url is not None:

items.append(self.url)

items.extend(self.children[name].to_nav(name) for name in sorted(self.children))

return {title: items}

def _compact_index(module: griffe.Module, documented: set[str]) -> str | None:

"""Build a compact page body for a module that re-exports from outside its own subtree.

mkdocstrings renders a re-export whose canonical documentation lives on

another page as a full duplicate of it, whether the alias stays within

one top-level package (`mcp.client.auth` re-exporting from

`mcp.shared.auth`) or crosses packages (`from mcp_types import y` +

`__all__` — `load_external_modules` in mkdocs.yml has the collector chase

exported cross-package aliases when their package is first collected, so

the target package is loaded regardless of page order). Modules whose

exports all live in their own subtree (`mcp_types` re-exporting its

private `._types` module, or a module whose `__all__` lists only its own

definitions) are unaffected and keep the plain `::: module` stub (return

`None`): their page is itself the canonical rendering.

For an affected module, replace the duplicates: every export whose

canonical page exists elsewhere under the API reference becomes a link to

it, and only exports documented nowhere else (re-exports from private

modules) keep their full body here, via an explicit `members:` list.

"""

prefix = f"{module.path}."

exports: dict[str, griffe.Object | griffe.Alias] = {}

for export in module.exports or ():

name = str(export)

# Listed exports must be statically documentable: a name provided at

# runtime (module `__getattr__`) is a docs error by policy, not a skip.

if (member := module.members.get(name)) is None:

msg = f"gen_ref_pages: export {module.path}.{name} is not statically visible"

raise SystemExit(msg)

exports[name] = member

if not any(member.is_alias and not member.target_path.startswith(prefix) for member in exports.values()):

return None

# A plain stub also renders the module's own public members that are not

# in `__all__` (`show_if_no_docstring: false` hides the docstring-less

# ones); keep them, so flipping a page to compact drops nothing.

public = dict(exports)

for name, member in module.members.items():

if (

name not in public

and not name.startswith("_")

and not member.is_alias

and member.kind is not griffe.Kind.MODULE

and member.has_docstrings

):

public[name] = member

inline: list[str] = []

sections: dict[str, list[str]] = {}

for name in sorted(public, key=str.lower):

member = public[name]

try:

target = member.final_target if member.is_alias else member

except griffe.AliasResolutionError as exc:

msg = f"gen_ref_pages: export {module.path}.{name} resolves outside the documented packages"

raise SystemExit(msg) from exc

# Link to the anchor another page actually renders: the deepest alias

# hop whose module is documented (the final target may live in a

# private module and only be re-exported by a public one), rendered

# there only when docstringed (`show_if_no_docstring: false`).

anchor = None

hop = member

while hop.is_alias:

if hop.target_path.rpartition(".")[0] in documented:

anchor = hop.target_path

hop = hop.target

if anchor is not None and member.has_docstrings:

link_target = anchor

else:

inline.append(name)

link_target = f"{module.path}.{name}"

entry = f"- [`{name}`][{link_target}]"

if docstring := target.docstring:

summary = " ".join(docstring.value.split("\n\n", 1)[0].split("\n"))

entry += f" — {summary}"

sections.setdefault(_KIND_SECTIONS[target.kind], []).append(entry)

body = [f"::: {module.path}", " options:"]

if inline:

body += [" members:", *(f" - {name}" for name in inline)]

else:

body += [" members: false"]

body.append("")

for title in _KIND_SECTIONS.values():

if title in sections:

body += [f"## {title}", "", *sections[title], ""]

return "\n".join(body)

def _stub(title: str, body: str) -> str:

"""A stub page: explicit title frontmatter plus the page body.

The explicit title matters: the stubs have no H1 of their own, and a

title-less page falls back to "Index"/the filename — which is what

pruned nav rows, browser tabs, and search results show.

"""

return f'---\ntitle: "{title}"\n---\n\n{body.rstrip()}\n'

def generate() -> list[NavItem]:

"""Write `docs/api/**.md` stubs and return the API-section navigation."""

if API_DIR.exists():

shutil.rmtree(API_DIR)

root = _Node()

stubs: dict[Path, str] = {}

pages: dict[str, Path] = {}

documented: set[str] = set()

for package in PACKAGES:

base = package.parent

for path in sorted(package.rglob("*.py")):

module_path = path.relative_to(base).with_suffix("")

doc_path = path.relative_to(base).with_suffix(".md")

parts = tuple(module_path.parts)

if parts[-1] == "__init__":

parts = parts[:-1]

doc_path = doc_path.with_name("index.md")

# A private component anywhere makes the module private: checking

# only the leaf would publish pages for e.g. mcp._vendor.util.

if any(part.startswith("_") for part in parts):

continue

ident = ".".join(parts)

if any(ident == e or ident.startswith(f"{e}.") for e in EXCLUDED):

continue

documented.add(ident)

stubs[API_DIR / doc_path] = _stub(parts[-1], f"::: {ident}")

pages[ident] = API_DIR / doc_path

node = root

for part in parts:

node = node.child(part)

node.url = f"api/{doc_path.as_posix()}"

# Load the root packages before inspecting any module: aliases only

# resolve once the module they point at is in the loader's collection.

loader = griffe.GriffeLoader(search_paths=[str(package.parent) for package in PACKAGES])

for package in PACKAGES:

loader.load(package.name)

for ident, doc_path in pages.items():

try:

module = loader.modules_collection[ident]

except KeyError as exc:

raise SystemExit(f"gen_ref_pages: cannot find {ident} in the loaded packages") from exc

if not isinstance(module, griffe.Module):

raise SystemExit(f"gen_ref_pages: {ident} is shadowed by a non-module member")

if body := _compact_index(module, documented):

stubs[doc_path] = _stub(ident.rpartition(".")[2], body)

for full_doc_path, stub in stubs.items():

full_doc_path.parent.mkdir(parents=True, exist_ok=True)

full_doc_path.write_text(stub, encoding="utf-8")

return [root.children[name].to_nav(name) for name in sorted(root.children)]

if __name__ == "__main__":

generate()