2 min read

Generate an API reference

Goal: publish a References section built automatically from a Python package's docstrings - exactly the section you see in this site's sidebar.

This is done with the apidoc contrib plugin (pyssg.contrib.apidoc). Contrib plugins are not auto re-exported into pyssg.plugins; import them from their module.

How it works

apidoc reads your package statically with the ast module - your code is never imported or executed. For each module it turns the docstrings into a virtual Markdown document and feeds it through the normal pipeline (markdown -> permalink -> nav -> render). Because the generated pages share a common URL prefix (/references/ by default), the nav plugin groups them into a single References section automatically.

Docstrings written in Google, NumPy, or reStructuredText style are parsed into structured parameter / return / raises tables; any other prose is kept verbatim. Nothing is ever written back into your content/ directory.

1. Add the plugin

from __future__ import annotations

from pyssg.contrib.apidoc import apidoc
from pyssg.presets import docs

config = docs(
    site={"title": "My Docs"},
    base_url="https://example.com",
    extra_plugins=[
        apidoc(package="../mypackage", route="/references/"),
    ],
)

package is resolved against the site directory: if your site lives in docs/ and your package in mypackage/ at the repository root, use "../mypackage". An absolute path works too. You may also point it at a single .py file.

2. Options

Option	Default	Meaning
`package`	(required)	Package directory or single module file (relative to the site root, or absolute).
`route`	`"/references/"`	URL prefix for the generated pages.
`include_private`	`False`	Include `_name` members and modules.
`include_dunder`	`False`	Include `__dunder__` members (`__init__` is always shown).

3. Build

pyssg --site docs build

The reference pages appear under the route you chose, one page per module, sorted by dotted name, and grouped into the sidebar's References section.

A note on incremental builds

The virtual documents are created once per build session (during the make hook). 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: restart serve or run build to pick up code changes.

This site

The page you are reading is generated by exactly this setup. See docs/pyssg.config.py - it adds apidoc(package="../pyssg", route="/references/") on top of the docs preset, which is what produces the References section in the sidebar.