# Generate API docs

## Install

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

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

Or install the CLI in an isolated environment with uv:

```bash
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](/python-autodoc/release-notes.md)
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:

```bash
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.

| Argument | Meaning |
| --- | --- |
| `source` | Python package directory, such as `src/my_package` or `my_package` |
| `--module` | Required import name, such as `my_package` |
| `--output` | Required output directory for generated `+Page.mdx` files |
| `--section` | Sidebar section; defaults to `Python API` |
| `--url-prefix` | Public route root for generated pages; defaults to `/api` |
| `--source-url` | Optional URL of the package directory at the documented revision |

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:

```text
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:

```bash
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:

```ts file="site.config.ts"
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:

```bash
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:

```bash
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](/guides/releases.md) 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](/python-autodoc.md#static-analysis-boundaries) 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.

```json file="api-pages.json"
{
  "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."
  }
}
```

```bash
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](https://params-proto.dreamlake.ai/reference)
for a site organized into configuration, environment, sweeps, CLI, and
compatibility topics.