Autodoc
Generated pages document a whole package. This is the default way to show your API reference.
<Autodoc> covers a different case: a page you write by hand that needs one class or function in
the middle of the text, rendered exactly as the generated pages render it. It is the component form
of mkdocstrings’ ::: demopkg.generate_report directive.
Migrating from mkdocstrings maps the rest of the directive’s
options onto props.
Put a block in a page
Section titled “Put a block in a page”The page must be .mdx. A .md page cannot import a component. This is usually the first problem
you hit. Starlight includes the MDX integration, so renaming the file is enough to fix it. A plain
Astro project needs to install @astrojs/mdx. Alternatively, write the page as .astro and put
the import in the frontmatter fence.
---title: Reporting---
{/* Import the component once, below the frontmatter. */}import { Autodoc } from 'starlight-pydocs/components';
The helper that writes one for you:
{/* Name the object where you want it rendered. */}<Autodoc name="demopkg.generate_report" package="api/demopkg" />
Pass `fmt` when you want something other than Markdown.name takes either the path an object is documented at, or the canonical path Griffe found the
definition at. Both paths reach the same object. package says which configured entry to read it
from.
That same line sits on this page. Everything in the box below is what it renders. The heading, the signature, the parameter table and the return value all come from the function’s own docstring. None of it comes from anything written here.
| Prop | Type | Default | What it does |
|---|---|---|---|
name |
string |
required | Dotted path of the object to document |
package |
string |
inferred from name |
Which configured entry to document it from |
headingLevel |
number |
2 |
Heading depth for the object; members go deeper |
labels |
StringOverrides |
site translations | UI label overrides for this block alone |
A class or function brings its members with it. Naming a module renders the whole module, the same
way a generated module page does, including the member summary and submodule list. A module has no
heading of its own here, so for a module, headingLevel sets the depth of its members.
labels lets a page in a plain Astro site translate a block. It also lets a Starlight site change
one string in one place. See
Internationalisation.
Choosing the package
Section titled “Choosing the package”The dotted name usually says which package an object belongs to, so package is optional. It
becomes required when one package is documented at more than one base, because then the import
name identifies two entries. Give it the base of the one you mean:
<Autodoc name="demopkg.report.Report" package="api/demopkg" /><Autodoc name="demopkg.report.Report" package="1x/api/demopkg" />This site documents demopkg twice (the current source and the archived 1.x dump), which is why
every block on this page names its base. Leave package off and the build stops with the
candidates listed:
starlight-pydocs: <Autodoc name="demopkg.report.Report"> is ambiguous: 'demopkg' is documented at 2 bases. Set the package prop to one of these bases: 'api/demopkg', '1x/api/demopkg'.package also accepts a plain import name where that name is unambiguous. A base always wins over
a name when both would match.
A name that resolves to a package, but not to an object in it, fails the same way. This is usually
a typo, or a members/filters setting that excludes the object from that entry:
starlight-pydocs: <Autodoc name="demopkg.report.Reprot"> is not documented at '/api/demopkg'. Check the spelling, or the members/filters options that may be excluding it.Heading levels
Section titled “Heading levels”headingLevel sets the depth of the object’s own heading. Its members go one level deeper. Use it
to place a block under a section of your own, without breaking the document outline:
## Building a report
The helper that wires one together for you:
<Autodoc name="demopkg.generate_report" package="api/demopkg" headingLevel={5} />Below is the same function as the block further up this page, rendered again at headingLevel={5}.
Its heading is an h5 instead of an h2, and its parameters sit at h6. Everything else about the
two blocks is identical.
Anchors and the table of contents
Section titled “Anchors and the table of contents”Every heading a block emits has the dotted object path as its id. This is the same anchor scheme
the generated pages and mkdocstrings use, so #demopkg.generate_report above is a working
permalink.
Those headings do not reach Starlight’s On this page panel. The panel is built from the
Markdown headings of the page itself, and a component’s output is not one of them. The panel
beside this guide proves it: it lists Heading levels, not demopkg.generate_report. Add your own
## heading above a block when you want a table of contents entry for it.
The generated pages stay an object’s canonical home either way.
Cross-references and the published objects.inv are
built from the page plan. So [Report][demopkg.report.Report] in a docstring resolves to the
generated demopkg.report page, never to a hand-placed copy of the same object.
Symbol search
Section titled “Symbol search”<SymbolSearch /> searches one package’s API surface by name. It runs client-side, using the
symbols.json index the plugin publishes. It is already on the generated package pages; this is
the same component placed by hand. It takes the same package prop, a base or an unambiguous
import name, and defaults to the first configured entry. Search
covers the index, the ranking and the rest of its props.
The box below searches demopkg. Type generate:
Type part of a name or a dotted path