Examples

Every Python package documented on this site is a test fixture from the plugin’s own repository, in fixtures/. Each fixture tests a different path through the plugin. One astro.config.ts file sets up all four. Start with the one that matches your setup.

demopkgGoogle-style docstrings, extracted from source at build time. Inheritance, re-exports, pydantic models and deprecations.

numpkgNumpy-style docstrings, parsed alongside a google-style package in the same build.

sphpkgSphinx-style docstrings from a checked-in dump. No Python runs at build time.

demopkg 1.xThe same package documented a second time at its own base, read from a dump rather than extracted.

demopkg

demopkg uses Google-style docstrings. The build extracts them from source with uvx --from griffe. It is the fixture that covers the most: docstring sections, inheritance with provenance, __all__, re-exports, pydantic models labelled through the griffe_pydantic extension, deprecations, and source links back to GitHub. Its pages are in the API reference section of the sidebar.

numpkg

numpkg also uses uvx --from griffe to extract docstrings from source, the same way as demopkg, but its docstrings are Numpy-style. Docstring style is a per-package setting. Griffe parses each package with a different parser, but both sit in the same API reference section of one build.

sphpkg

sphpkg uses Sphinx-style docstrings. The plugin renders them from a checked-in griffe dump instead of extracting them, so no Python runs at build time. See Pre-generated dumps: the dump comes from the Python project’s CI, and the docs site only reads it. Its sidebar section is Sphinx demo.

demopkg 1.x

demopkg 1.x has the same import name as demopkg. The docs site documents it a second time, at its own base (/1x/api/demopkg/), under the v1.x sidebar section, and reads it from a dump instead of extracting it from source. This is the shape that versioned docs take: one packages entry per release, each with its own base, sidebar section, and endpoints.

Both entries here read the same fixture, so the two trees document identical code. This example shows the wiring between a package and its base, not a real difference between versions. On a real site, you would point each entry at the dump that its own release published.

Endpoints

Each package serves machine-readable versions of its pages next to the pages themselves. These are the live ones for demopkg:

• symbols.json: the index behind the symbol search box.
• objects.inv: the Sphinx inventory other projects link against (Cross-references).
• llms.txt: the whole API as plain Markdown (llms.txt).

Vanilla Astro

examples/vanilla in the repository documents demopkg again, in a plain Astro site with no Starlight. It uses the built-in layout and its own markdown pipeline. This example is not deployed here. See the guide or the source.