Python API reference documentation for Starlight and plain Astro sites. It reads your package with Griffe and renders the result with Astro components on injected routes, one page per module. Extraction is static analysis, so nothing is imported and nothing needs installing.

It is the Starlight counterpart of mkdocstrings-python and follows its conventions where possible.

Documentation and examples: ewels.github.io/starlight-pydocs 📚

Features

• 📄 Generated pages
  • One page per module, injected into the site's routes, with a sidebar tree and prev/next links that mirror the package layout
• 🎯 Autodoc component
  • <Autodoc name="mypkg.Report" /> renders a single class or function into a hand-written MDX page
• 🔍 Symbol search
  • Search the API surface by object path, on top of the site's existing prose search
• 📝 Docstring sections
  • Google, numpy or sphinx style: parameters, returns, raises, examples, admonitions and deprecations, rendered by your site's own Markdown pipeline
• 🐍 Autogenerate at build time, or supply JSON
  • Point the plugin at a dump your CI published and the site builds without a Python interpreter
• 🔗 Linked signatures
  • Names in an annotation link to their definition on your own pages or, through a Sphinx inventory, to another project's documentation
• 🧬 Inherited members
  • Merged from resolvable base classes and labelled with the class they came from
• 📚 Inventory and Markdown
  • objects.inv and llms.txt per package, plus every page as Markdown at <path>.md and <path>.md.txt, so other documentation sites and language models can consume yours

Installation

npm install starlight-pydocs

Usage

As a Starlight plugin

Name the package, point search at the directory that contains it, and put the sidebar placeholder where the generated pages belong:

// astro.config.mjs
import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import starlightPydocs, { pydocsSidebarGroup } from 'starlight-pydocs';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My project',
      plugins: [
        starlightPydocs({
          packages: [{ name: 'mypkg', search: ['../src'] }],
          inventories: ['python'],
        }),
      ],
      sidebar: [{ label: 'API reference', items: [pydocsSidebarGroup] }],
    }),
  ],
});

mypkg is documented at /api/mypkg/, one page per module, alongside symbols.json, objects.inv and llms.txt. Every page also answers at its own path plus .md or .md.txt.

In any Astro project

starlight-pydocs/astro injects the same routes with a minimal built-in layout, overridable with the layout option. Nothing in its module graph imports Starlight:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import pydocs from 'starlight-pydocs/astro';

export default defineConfig({
  integrations: [pydocs({ packages: [{ name: 'mypkg', search: ['../src'] }] })],
});

One object in a hand-written page

<Autodoc> is the equivalent of mkdocstrings' ::: mypkg.Thing directive, and renders exactly what the generated pages render:

import { Autodoc } from 'starlight-pydocs/components';

<Autodoc name="mypkg.Thing" />
<Autodoc name="mypkg.build" headingLevel={3} />

Requirements

• Node ≥ 22.12 and Astro ≥ 7.
• Starlight ≥ 0.41 for the plugin. The Astro integration needs no Starlight at all.
• Python only where extraction runs. uv on PATH is enough (the runner uses uvx --from griffe griffe), or an interpreter with griffe importable for python -m griffe. A pre-generated dump (source: { file } or source: { url }) needs no Python on the docs host.

Documentation

The documentation site documents three example Python packages with the plugin, so every API page on it is also a live demo of the output.

Getting started   |   Examples   |   Configuration   |   Migrating from mkdocstrings   |   llms.txt for AI models   |   Agent skill

License

This project is licensed under the MIT License.

Credits

• Created by Phil Ewels
• Built on Griffe by Timothée Mazzucotelli, whose mkdocstrings-python set the conventions this plugin follows.
• Logotype set in Michroma (SIL Open Font License).

[!TIP] Writing docs with MkDocs instead? Use mkdocstrings-python, which documents the same Griffe model for MkDocs and Material for MkDocs.