# Autodoc

URL: /bengal/docs/content/sources/autodoc/
Section: sources
Description: Generate API docs from source code

---

> For a complete page index, fetch /bengal/llms.txt.

Generate API documentation automatically from source code during site builds.

## Do I Need This?

:::{note}
**Skip this if**: You write all documentation manually.  
**Read this if**: You want API docs from Python docstrings, CLI help from Click/Typer commands, or API specs from OpenAPI.
:::

## How It Works

Autodoc generates **virtual pages** during your site build. No intermediate markdown files are created. Configure sources in your `bengal.toml` and documentation appears in your built site.

```mermaid
flowchart LR
    subgraph Sources
        A[Python Modules]
        B[CLI Commands]
        C[OpenAPI Specs]
    end

    D[Autodoc Engine]

    subgraph Output
        E[Virtual Pages]
    end

    A --> D
    B --> D
    C --> D
    D --> E
```

## Configuration

Configure autodoc in your `bengal.toml`:

:::{tab-set}
:::{tab-item} Python
```toml
# bengal.toml
[autodoc.python]
enabled = true
source_dirs = ["mypackage"]
include_private = false
include_special = false
docstring_style = "auto"  # auto, google, numpy, sphinx
```

Extracts:
- Module and class docstrings
- Function signatures and type hints
- Examples from docstrings
:::{/tab-item}

:::{tab-item} CLI
```toml
# bengal.toml
[autodoc.cli]
enabled = true
app_module = "mypackage.cli:main"  # Click/Typer app entry point
framework = "click"  # click, argparse, or typer
include_hidden = false
```

Extracts:
- Command descriptions
- Argument documentation
- Option flags and defaults
:::{/tab-item}

:::{tab-item} OpenAPI
```toml
# bengal.toml
[autodoc.openapi]
enabled = true
spec_file = "api/openapi.yaml"
```

Extracts:
- Endpoint documentation
- Request/response schemas
- Authentication requirements

Local OpenAPI `$ref` files are supported relative to the document that declares
the reference, such as `./schemas.yaml#/User`. Bengal tracks those files as
autodoc dependencies for incremental rebuilds. Remote URL refs are intentionally
left unresolved.
:::{/tab-item}
:::{/tab-set}

## Python Configuration Options

```toml
[autodoc.python]
enabled = true

# Source directories to scan
source_dirs = ["mypackage"]

# Patterns to exclude
exclude = [
    "*/tests/*",
    "*/__pycache__/*",
    "*/.venv/*",
]

# Docstring parsing style: auto, google, numpy, sphinx
docstring_style = "auto"

# Include private members (_prefixed)
include_private = false

# Include dunder methods (__init__, etc.)
include_special = false

# Include inherited members
include_inherited = false

# When module has __all__, only document those names
respect_all = true

# Member order: source (definition order), alphabetical, or type
member_order = "source"

# Show compact summary table at top of module pages
show_member_summary = false

# Per-module overrides (e.g. include_private for specific modules)
# overrides = { "mypkg.internal" = { include_private = true } }

# Prefix to strip from module paths
strip_prefix = "mypackage"
```

## Building with Autodoc

Once configured, autodoc runs automatically during builds:

```bash
bengal build
```

The generated API documentation appears in your output directory alongside your regular content.

## Performance Optimizations

Bengal automatically optimizes autodoc builds:

- **AST Caching**: Parsed Python modules are cached between builds. Unchanged source files skip AST parsing entirely, providing 30-40% speedup for sites with many autodoc pages.
- **Selective Rebuilds**: Only autodoc pages affected by changed source files are rebuilt during incremental builds.
- **Parallel Extraction**: Python modules are extracted in parallel when multiple files are present.

These optimizations are automatic and require no configuration.

## Navigation (topbar)

If you do not define `menu.main`, Bengal generates a topbar menu automatically.

- **Manual menu overrides auto menu**: If `menu.main` is present and non-empty, Bengal uses it and does not auto-discover topbar items.
- **Dev dropdown**: In auto mode, Bengal may bundle autodoc outputs under a **Dev** dropdown when multiple “dev” links exist. If there is only one dev link (for example, API-only or CLI-only), it appears as a normal top-level menu entry.

If you want full control of where autodoc appears in the topbar, define `menu.main`.

## Strict Mode

Enable strict mode to fail builds on extraction or rendering errors:

```toml
[autodoc]
strict = true
```

:::{tip}
**Best practice**: Enable strict mode in CI pipelines to catch documentation issues early.
:::

:::{seealso}
- [Architecture Reference](/docs/reference/architecture/subsystems/autodoc) — Technical details and API usage
:::