Generate API docs

Install

The generator requires Python 3.10 or later and has no runtime dependencies.

python -m pip install dreamlake-autodoc-py==0.2.0a1

Or install the CLI in an isolated environment with uv:

uv tool install 'dreamlake-autodoc-py==0.2.0a1'

The distribution name is dreamlake-autodoc-py, and the command is autodoc-py. This is a standard Python package using setuptools; uv can install and build it without a separate uv-specific package format. See Release notes for distribution status.

For a reproducible build, append @COMMIT_SHA to the Git URL, replacing the placeholder with the exact generator revision you have reviewed. The generator revision and your documented package revision are separate choices.

Generate pages

Pass the directory containing the Python package, its import name, and the destination under your Dockit pages/ directory:

autodoc-py src/my_package \
  --module my_package \
  --output docs/pages/api \
  --section 'Python API' \
  --source-url https://github.com/example/my-project/blob/RELEASE_SHA/src/my_package

Replace RELEASE_SHA with the documented source revision. --source-url points to the package directory, so its path should correspond to the input directory.

You can invoke the same CLI through python -m autodoc_py after installation.

Output layout

For a package containing __init__.py, client.py, and models/item.py, output follows this structure:

docs/pages/api/
  +Page.mdx
  client/+Page.mdx
  models/item/+Page.mdx
  .autodoc-py.json

The package page is served at /api, while the module pages appear at /api/client and /api/models/item. Frontmatter supplies the page title, section, order, and description.

Custom API routes

If the output lives at docs/pages/reference/python, set the matching public route prefix:

autodoc-py src/my_package --module my_package \
  --output docs/pages/reference/python \
  --url-prefix /reference/python

The generator uses absolute routes for module and re-export links, so they resolve both with and without a trailing slash. The output path controls where files are written; --url-prefix controls their public links.

Regeneration

Run the same command after changing your Python source. All source files are parsed before output changes, so a syntax error stops generation before replacing pages.

The .autodoc-py.json manifest tracks generated files. Keep it with the generated pages so a later run can remove obsolete output. Keep hand-written introductions and tutorials outside the generated paths: pages still owned by the generator are replaced during regeneration.

Docstrings and code

MDX expression and JSX characters in prose are escaped. Inline code and fenced examples retain their formatting. Write explanatory docstrings and explicit signatures in the Python source; keep narrative tutorials as hand-written MDX pages.

Sphinx directives remain text rather than executing a Sphinx extension pipeline. For a project that depends heavily on Sphinx, inspect the generated reference and retain its existing builds while migrating.

Dockit integration

Add the sidebar section

Include your chosen section in the site configuration to control its position:

initDocs({
  site: { brand: 'My project', subtitle: 'Docs' },
  pages,
  rawPages,
  sectionOrder: ['Getting started', 'Guides', 'Python API'],
})

Use --section 'Python API' when generating the pages. If your site uses tabs, give the API tab a urlPrefix matching the output path, such as /api for docs/pages/api.

Build in sequence

Generate before running Vite so the build, search index, and LLM exports see the same pages:

autodoc-py src/my_package --module my_package \
  --output docs/pages/api --section 'Python API'
pnpm build

Install the pinned generator in CI, then run these steps against the checked-out package source. Commit generated MDX and its manifest if you want reference changes reviewed as a diff; alternatively generate them consistently in CI before every docs build.

Use the workspace submodule

The Dockit workspace includes the generator source at packages/autodoc-py. Initialize it when cloning the workspace:

git submodule update --init --recursive
python -m pip install -e packages/autodoc-py

The parent repository records the submodule revision. Updating that recorded revision is an explicit change, so builds can keep using a reviewed generator version even as the generator repository evolves.

The Python package is independent of the JavaScript workspace. A normal Dockit build does not install Python or generate API pages unless your build workflow adds that step.

Versioned documentation

For each documentation branch:

1. Check out the matching package release.
2. Run the pinned generator against that release's package directory.
3. Set --source-url to the same release commit.
4. Build and inspect the complete static site before publishing the branch.

Older releases may use a different package layout or Python syntax. Match the source path and interpreter to the release; do not generate every branch from today's source tree.

Keep existing build artifacts until their replacements are verified. A version menu can link to an earlier Sphinx site while a Dockit branch is being prepared. See Releases and versioning for branch deploys and the versions.json manifest.

Verify the result

Check a package page, a module page, a class with inherited members, and a source link. Confirm that navigation resolves under your deployed URL, search finds an API symbol, and the generated manifest only owns the expected files.

Static extraction cannot reproduce runtime-generated APIs. Supplement those cases with hand-written reference pages, and use the documented limitations when interpreting the result.

Group modules into topic pages

The default layout creates one page per Python module. When the module tree contains small implementation files, use --page-map to choose reader-facing topics instead. Each topic has an introduction, a linked API index, and sections for its functions and classes. Methods stay beneath their classes.

{
  "pages": [
    {
      "slug": "configuration",
      "title": "Configuration",
      "description": "Configure a client and read environment values.",
      "intro": "Start with Client; use the environment helpers for defaults.",
      "modules": ["my_package", "my_package.config", "my_package.env"]
    },
    {
      "slug": "jobs",
      "title": "Jobs",
      "description": "Submit and inspect jobs.",
      "modules": ["my_package.jobs*"]
    }
  ],
  "exclude": {
    "my_package.internal*": "Implementation helpers, not public API."
  }
}

autodoc-py src/my_package --module my_package \
  --output docs/pages/reference --url-prefix /reference \
  --page-map api-pages.json

Every public module must match exactly one topic or an explicit exclusion. An optional symbols object maps module names to lists of selected public symbols. References to excluded modules or omitted symbols fail validation instead of silently producing broken links.

Anchors include the defining module so similarly named classes on a combined page remain distinct. .autodoc-routes.json records old module and symbol URLs for site-specific redirects. The existing generated-file manifest removes old module pages while preserving hand-written pages.

Public callable singletons such as EnvVar = _EnvVar() are documented without executing their constructors. Google-style argument and return sections become readable lists, and indented examples become fenced Python code.

See params-proto's API reference for a site organized into configuration, environment, sweeps, CLI, and compatibility topics.