3 min read

pyssg.contrib.apidoc

Contrib plugin: API reference from Python docstrings.

Extracts docstrings from a Python package statically (via :mod:ast, so the user's code is never imported or executed) and turns each module into a virtual Markdown document under a /references/ route. The synthetic Markdown is fed through the normal pipeline (markdown -> permalink -> nav -> render), so the output is ordinary HTML and the modules automatically form a "References" section in the sidebar (the nav plugin groups pages by their first URL segment).

It never touches the user's source Markdown: the generated documents live only in the build graph (meta["__raw__"]); nothing is written back to content.

Docstrings written in Google, NumPy or reStructuredText style are parsed into structured parameter/return/raises tables; any other prose is kept verbatim. Tables are emitted as raw HTML because the engine renders Markdown with the CommonMark preset, which has no GFM table syntax (raw HTML passes through).

Purity / incremental notes:

• Extraction is a pure function of the .py files on disk: modules and members are emitted in source order, nothing reads the clock or environment, so two builds are byte-identical and an incremental rebuild equals a full one.
• The virtual documents are created during make (once per session). A full build -- and every serve startup -- reflects the current .py files. Live hot-reload when a .py file changes mid-serve is intentionally out of scope for now (it would require the engine to watch and seed non-Markdown source files); restart serve or run build to pick up code changes.

Third-party imports are allowed here (this is periphery, not pyssg.core), but this plugin needs none: it is pure standard library.

class Param

One named field of a docstring (a parameter, a return, or a raise).

name is the parameter / exception name (empty for an anonymous return), type the declared type (may be empty), description the free text.

class ParsedDocstring

A docstring split into a summary, typed fields, and verbatim sections.

parse_docstring(text: str) -> ParsedDocstring

Parse a (cleaned) docstring into a :class:ParsedDocstring.

The style is auto-detected; an unrecognised docstring becomes an all-summary result so nothing is ever dropped.

render_docstring_markdown(doc: ParsedDocstring) -> str

Render a parsed docstring back to Markdown (summary + HTML tables).

module_markdown(dotted: str, tree: ast.Module, *, include_private: bool, include_dunder: bool) -> str

Render one module's docstrings to a Markdown document (source order).

extract_package(root: Path, *, include_private: bool = False, include_dunder: bool = False) -> list[tuple[str, str]]

Extract (dotted_name, markdown) for every module under root.

root may be a package directory or a single .py file. Results are sorted by dotted name (deterministic). Files that fail to parse are skipped.

class ApiDocPlugin

Generates a References section from a package's docstrings.

ApiDocPlugin.__init__(self, *, package: str | Path, route: str = '/references/', include_private: bool = False, include_dunder: bool = False) -> None

ApiDocPlugin.apply(self, builder: Builder) -> None

apidoc(*, package: str | Path, route: str = '/references/', include_private: bool = False, include_dunder: bool = False) -> ApiDocPlugin

Factory used in pyssg.config.py.

Parameters