Module

autodoc.base

Base classes for autodoc system.

Provides common interfaces for all documentation extractors.

View source
2 Classes

Classes

DocElement dataclass
Represents a documented element (function, class, endpoint, command, etc.). This is the unified da…
3

Represents a documented element (function, class, endpoint, command, etc.).

This is the unified data model used by all extractors. Each extractor converts its specific domain into this common format.

Attributes

Name Type Description
name str

Element name (e.g., 'build', 'Site', 'GET /users')
qualified_name str

Full path (e.g., 'bengal.core.site.Site.build')
description str

Main description/docstring
element_type str

Type of element ('function', 'class', 'endpoint', 'command', etc.)
source_file Path | None

Source file path (if applicable)
line_number int | None

Line number in source (if applicable)
metadata dict[str, Any]

Type-specific data (signatures, parameters, etc.)
typed_metadata DocMetadata | None
children list[DocElement]

Nested elements (methods, subcommands, etc.)
examples list[str]

Usage examples
see_also list[str]

Cross-references to related elements
deprecated str | None

Deprecation notice (if any)

Methods 2

to_dict
Convert to dictionary for caching/serialization.
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Convert to dictionary for caching/serialization.

Returns

dict[str, Any]

from_dict classmethod
Create from dictionary (for cache loading).
1 DocElement 
def from_dict(cls, data: dict[str, Any]) -> DocElement

Create from dictionary (for cache loading).

Parameters 1
data dict[str, Any]
Returns

DocElement

Internal Methods 1
_deserialize_typed_metadata staticmethod
Deserialize typed_metadata from dict.
1 DocMetadata | None 
def _deserialize_typed_metadata(data: dict[str, Any]) -> DocMetadata | None

Deserialize typed_metadata from dict.

Parameters 1
data dict[str, Any]

Dict with "type" and "data" keys
Returns

DocMetadata | None —

Typed metadata instance or None

Extractor abstract
Base class for all documentation extractors. Each documentation type (Python, OpenAPI, CLI) implem…
2

Base class for all documentation extractors.

Each documentation type (Python, OpenAPI, CLI) implements this interface. This enables a unified API for generating documentation from different sources.

Inherits from ABC

Methods 2

extract
Extract documentation elements from source.
1 list[DocElement] 
def extract(self, source: Any) -> list[DocElement]

Extract documentation elements from source.

Parameters 1
source Any

Source to extract from (Path for files, dict for specs, etc.)
Returns

list[DocElement] —

List of DocElement objects representing the documentation structure

get_output_path
Determine output path for an element.
1 Path | None 
def get_output_path(self, element: DocElement) -> Path | None

Determine output path for an element.

Parameters 1
element DocElement

Element to generate path for
Returns

Path | None —

Relative path for the generated markdown file, or None if the element should be skipped (e.g., stripped prefix packages)