Module

autodoc.virtual_orchestrator

Virtual page orchestrator for autodoc.

Generates API documentation as virtual Page and Section objects that integrate directly into the build pipeline without intermediate markdown files.

This is the new architecture that replaces markdown-based autodoc generation.

View source
3 Classes 1 Function

Classes

AutodocRunResult dataclass
Summary of an autodoc generation run. Tracks successes, failures, and warnings for observability a…
3

Summary of an autodoc generation run.

Tracks successes, failures, and warnings for observability and strict mode enforcement.

Attributes

Name Type Description
extracted int
rendered int
failed_extract int
failed_render int
warnings int
failed_extract_identifiers list[str]
failed_render_identifiers list[str]
fallback_pages list[str]
autodoc_dependencies dict[str, set[str]]

Methods 3

has_failures
Check if any failures occurred.
0 bool 
def has_failures(self) -> bool

Check if any failures occurred.

Returns

bool

has_warnings
Check if any warnings occurred.
0 bool 
def has_warnings(self) -> bool

Check if any warnings occurred.

Returns

bool

add_dependency
Register a dependency between a source file and an autodoc page.
2 None 
def add_dependency(self, source_file: str, page_path: str) -> None

Register a dependency between a source file and an autodoc page.

Parameters 2
source_file str

Path to the Python/OpenAPI source file
page_path str

Path to the generated autodoc page (source_path)
_PageContext
Lightweight page-like context for autodoc template rendering. Templates extend base.html and inclu…
2

Lightweight page-like context for autodoc template rendering.

Templates extend base.html and include partials that expect a 'page' variable with attributes like metadata, tags, title, and relative_url. This class provides those attributes without requiring a full Page object (which doesn't exist yet during the initial render phase).

The navigation attributes (prev, next, prev_in_section, next_in_section) are set to None since autodoc virtual pages don't participate in linear navigation.

Internal Methods 2
__init__
7 None 
def __init__(self, title: str, metadata: dict[str, Any], tags: list[str] | None = None, relative_url: str = '/', variant: str | None = None, source_path: str | None = None, section: Section | None = None) -> None
Parameters 7
title str
metadata dict[str, Any]
tags list[str] | None
relative_url str
variant str | None
source_path str | None
section Section | None
__repr__
0 str 
def __repr__(self) -> str
Returns

str

VirtualAutodocOrchestrator
Orchestrate API documentation generation as virtual pages. This orchestrator creates virtual Page …
23

Orchestrate API documentation generation as virtual pages.

This orchestrator creates virtual Page and Section objects that integrate directly into the site's build pipeline, rendered via theme templates without intermediate markdown files.

Architecture:

1. Extract DocElements from source (Python, CLI, or OpenAPI)
2. Create virtual Section hierarchy based on element type
3. Create virtual Pages for each documentable element
4. Return (pages, sections) tuple for integration into site

Supports:

  • Python API docs (modules, classes, functions)
  • CLI docs (commands, command groups)
  • OpenAPI docs (endpoints, schemas)

Benefits over markdown-based approach:

  • No intermediate markdown files to manage
  • Direct HTML rendering (bypass markdown parsing)
  • Better layout control (card-based API Explorer)
  • Faster builds (no parse → render → parse cycle)

Methods 2

is_enabled
Check if virtual autodoc is enabled for any type.
0 bool 
def is_enabled(self) -> bool

Check if virtual autodoc is enabled for any type.

Returns

bool

generate
Generate documentation as virtual pages and sections for all enabled types.
0 tuple[list[Page], l… 
def generate(self) -> tuple[list[Page], list[Section], AutodocRunResult]

Generate documentation as virtual pages and sections for all enabled types.

Returns

tuple[list[Page], list[Section], AutodocRunResult] —

Tuple of (pages, sections, result) to add to site

Internal Methods 21
__init__
Initialize virtual autodoc orchestrator.
1 None 
def __init__(self, site: Site)

Initialize virtual autodoc orchestrator.

Parameters 1
site Site

Site instance for configuration and context
_relativize_paths
Convert absolute paths in error messages to project-relative paths. Makes erro…
1 str 
def _relativize_paths(self, message: str) -> str

Convert absolute paths in error messages to project-relative paths.

Makes error messages less noisy by showing paths relative to the project root (e.g., /bengal/themes/... instead of /Users/name/.../bengal/themes/...).

Parameters 1
message str

Error message that may contain absolute paths
Returns

str —

Message with absolute paths converted to project-relative paths

_create_template_environment
Create Jinja2 environment for HTML templates.
0 Environment 
def _create_template_environment(self) -> Environment

Create Jinja2 environment for HTML templates.

Returns

Environment

_get_theme_templates_dir
Get theme templates directory if available.
0 Path | None 
def _get_theme_templates_dir(self) -> Path | None

Get theme templates directory if available.

Returns

Path | None

_create_python_sections
Create virtual section hierarchy from doc elements. Creates sections for: - /a…
1 dict[str, Section] 
def _create_python_sections(self, elements: list[DocElement]) -> dict[str, Section]

Create virtual section hierarchy from doc elements.

Creates sections for:

  • /api/ (root API section)
  • /api/<package>/ (for each top-level package)
  • /api/<package>/<subpackage>/ (nested packages)
Parameters 1
elements list[DocElement]

List of DocElements (modules) to process
Returns

dict[str, Section] —

Dictionary mapping section path to Section object

_create_cli_sections
Create CLI section hierarchy.
1 dict[str, Section] 
def _create_cli_sections(self, elements: list[DocElement]) -> dict[str, Section]

Create CLI section hierarchy.

Parameters 1
elements list[DocElement]
Returns

dict[str, Section]

_create_openapi_sections
Create OpenAPI section hierarchy.
2 dict[str, Section] 
def _create_openapi_sections(self, elements: list[DocElement], existing_sections: dict[str, Section] | None = None) -> dict[str, Section]

Create OpenAPI section hierarchy.

Parameters 2
elements list[DocElement]
existing_sections dict[str, Section] | None
Returns

dict[str, Section]

_create_pages
Create virtual pages for documentation elements. This uses a two-pass approach…
4 tuple[list[Page], A… 
def _create_pages(self, elements: list[DocElement], sections: dict[str, Section], doc_type: str = 'python', result: AutodocRunResult | None = None) -> tuple[list[Page], AutodocRunResult]

Create virtual pages for documentation elements.

This uses a two-pass approach to ensure navigation works correctly:

  1. First pass: Create all Page objects and add them to sections
  2. Second pass: Render HTML (now sections have all their pages)
Parameters 4
elements list[DocElement]

DocElements to create pages for
sections dict[str, Section]

Section hierarchy for page placement
doc_type str

Type of documentation ("python", "cli", "openapi")
result AutodocRunResult | None

AutodocRunResult to track failures and warnings
Returns

tuple[list[Page], AutodocRunResult] —

Tuple of (list of virtual Page objects, updated result)

_find_parent_section
Find the appropriate parent section for an element.
3 Section 
def _find_parent_section(self, element: DocElement, sections: dict[str, Section], doc_type: str) -> Section

Find the appropriate parent section for an element.

Parameters 3
element DocElement
sections dict[str, Section]
doc_type str
Returns

Section

_create_element_page
Create a virtual page for any element type.
3 Page 
def _create_element_page(self, element: DocElement, section: Section, doc_type: str) -> Page

Create a virtual page for any element type.

Parameters 3
element DocElement

DocElement to create page for
section Section

Parent section for this page
doc_type str

Type of documentation ("python", "cli", "openapi")
Returns

Page —

Virtual Page object

_get_element_metadata
Get template name, URL path, and page type for an element.
2 tuple[str, str, str] 
def _get_element_metadata(self, element: DocElement, doc_type: str) -> tuple[str, str, str]

Get template name, URL path, and page type for an element.

Parameters 2
element DocElement
doc_type str
Returns

tuple[str, str, str]

_render_element
Render element documentation to HTML.
5 str 
def _render_element(self, element: DocElement, template_name: str, url_path: str, page_type: str, section: Section | None = None) -> str

Render element documentation to HTML.

Parameters 5
element DocElement

DocElement to render
template_name str

Template name (e.g., "api-reference/module")
url_path str

URL path for this element (e.g., "cli/bengal/serve")
page_type str

Page type (e.g., "cli-reference", "api-reference")
section Section | None

Parent section (for sidebar navigation)
Returns

str —

Rendered HTML string

_render_fallback
Render minimal fallback HTML when template fails.
1 str 
def _render_fallback(self, element: DocElement) -> str

Render minimal fallback HTML when template fails.

Parameters 1
element DocElement
Returns

str

_render_fallback_class
Render minimal class HTML.
1 str 
def _render_fallback_class(self, element: DocElement) -> str

Render minimal class HTML.

Parameters 1
element DocElement
Returns

str

_render_fallback_function
Render minimal function HTML.
1 str 
def _render_fallback_function(self, element: DocElement) -> str

Render minimal function HTML.

Parameters 1
element DocElement
Returns

str

_create_index_pages
Create index pages for sections that need them.
1 list[Page] 
def _create_index_pages(self, sections: dict[str, Section]) -> list[Page]

Create index pages for sections that need them.

Parameters 1
sections dict[str, Section]

Section dictionary to process
Returns

list[Page] —

List of created index pages (to add to main pages list)

_render_section_index
Render section index page HTML.
1 str 
def _render_section_index(self, section: Section) -> str

Render section index page HTML.

Parameters 1
section Section
Returns

str

_render_section_index_fallback
Fallback card-based rendering when template fails.
1 str 
def _render_section_index_fallback(self, section: Section) -> str

Fallback card-based rendering when template fails.

Parameters 1
section Section
Returns

str

_extract_python
Extract Python API documentation.
0 list[DocElement] 
def _extract_python(self) -> list[DocElement]

Extract Python API documentation.

Returns

list[DocElement]

_extract_cli
Extract CLI documentation.
0 list[DocElement] 
def _extract_cli(self) -> list[DocElement]

Extract CLI documentation.

Returns

list[DocElement]

_extract_openapi
Extract OpenAPI documentation.
0 list[DocElement] 
def _extract_openapi(self) -> list[DocElement]

Extract OpenAPI documentation.

Returns

list[DocElement]

Functions

_format_source_file_for_display
Normalize source_file paths for GitHub links. - Prefer paths relative to the project root - Otherw…
2 str | None 
def _format_source_file_for_display(source_file: Path | str | None, root_path: Path) -> str | None

Normalize source_file paths for GitHub links.

  • Prefer paths relative to the project root
  • Otherwise return the POSIX-ified absolute path

Parameters 2

Name Type Default Description
source_file Path | str | None —
root_path Path —

Returns

str | None