# Autodoc URL: /bengal/docs/0.5.0/content/sources/autodoc/ Section: sources Tags: autodoc, api-docs, python, cli, openapi -------------------------------------------------------------------------------- Autodoc Generate API documentation automatically from source code during site builds. Do I Need This? Note 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. 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: Python CLI OpenAPI # 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 # 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 # bengal.toml [autodoc.openapi] enabled = true spec_file = "api/openapi.yaml" Extracts: Endpoint documentation Request/response schemas Authentication requirements Full consolidated endpoint references with parameters, request bodies, responses, and generated request examples 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. Python Configuration Options [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: 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: [autodoc] strict = true Tip Tip Best practice: Enable strict mode in CI pipelines to catch documentation issues early. Info Seealso Architecture Reference — Technical details and API usage -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 596 - Reading Time: 3 minutes