Autodoc

Generate API docs from source code

2 min read 380 words

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 commands, or API specs from OpenAPI.

How It Works

Autodoc generates virtual pages during your site build — no intermediate markdown files are created. Simply configure the sources in yourbengal.tomland the documentation appears in your built site.

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 yourbengal.toml:

1
2
3
4
5
6
7
# 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
1
2
3
4
5
6
# bengal.toml
[autodoc.cli]
enabled = true
app_module = "mypackage.cli:main"  # Click app entry point
framework = "click"  # click, argparse, or typer
include_hidden = false

Extracts:

  • Command descriptions
  • Argument documentation
  • Option flags and defaults
1
2
3
4
# bengal.toml
[autodoc.openapi]
enabled = true
spec_file = "api/openapi.yaml"

Extracts:

  • Endpoint documentation
  • Request/response schemas
  • Authentication requirements

Python Configuration Options

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
[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

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

Building with Autodoc

Once configured, autodoc runs automatically during builds:

bengal build

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

Strict Mode

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

1
2
[autodoc]
strict = true

Tip

Best practice: Enable strict mode in CI pipelines to catch documentation issues early.

Seealso