Module

cache.build_cache.autodoc_tracking

Autodoc dependency tracking mixin for BuildCache.

Tracks which Python source files produce which autodoc pages, enabling selective regeneration of autodoc pages when their source files change.

Key Concepts:

  • Source file tracking: Maps Python/OpenAPI source files to autodoc page paths
  • Selective invalidation: Only rebuild affected autodoc pages, not all
  • Orphan cleanup: Remove autodoc pages when source files are deleted

Related Modules:

  • bengal.autodoc.virtual_orchestrator: Creates autodoc pages with dependencies
  • bengal.orchestration.incremental: Uses dependency info for selective builds

See Also:

  • plan/active/rfc-autodoc-incremental-builds.md: Design rationale
View source
1 Class

Classes

AutodocTrackingMixin
Track autodoc source file to page dependencies. This mixin adds dependency tracking for autodoc pa…
6

Track autodoc source file to page dependencies.

This mixin adds dependency tracking for autodoc pages, enabling selective rebuilds when only specific Python/OpenAPI source files change.

Attributes

Name Type Description
autodoc_dependencies dict[str, set[str]]

Mapping of source_file path to set of autodoc page paths that are generated from that source file.

Methods 6

add_autodoc_dependency
Register that source_file produces autodoc_page.
2 None 
def add_autodoc_dependency(self, source_file: Path | str, autodoc_page: Path | str) -> None

Register that source_file produces autodoc_page.

Parameters 2
source_file Path | str

Path to the Python/OpenAPI source file
autodoc_page Path | str

Path to the generated autodoc page (source_path)
get_affected_autodoc_pages
Get autodoc pages affected by a source file change.
1 set[str] 
def get_affected_autodoc_pages(self, changed_source: Path | str) -> set[str]

Get autodoc pages affected by a source file change.

Parameters 1
changed_source Path | str

Path to the changed Python/OpenAPI source file
Returns

set[str] —

Set of autodoc page paths that need to be rebuilt

get_autodoc_source_files
Get all tracked autodoc source files.
0 set[str] 
def get_autodoc_source_files(self) -> set[str]

Get all tracked autodoc source files.

Returns

set[str] —

Set of all source file paths that have autodoc dependencies

clear_autodoc_dependencies
Clear all autodoc dependency mappings. Called when autodoc configuration chang…
0 None 
def clear_autodoc_dependencies(self) -> None

Clear all autodoc dependency mappings.

Called when autodoc configuration changes to ensure fresh mappings.

remove_autodoc_source
Remove a source file and return its associated autodoc pages.
1 set[str] 
def remove_autodoc_source(self, source_file: Path | str) -> set[str]

Remove a source file and return its associated autodoc pages.

Parameters 1
source_file Path | str

Path to the source file being removed
Returns

set[str] —

Set of autodoc page paths that were associated with this source

get_autodoc_stats
Get statistics about autodoc dependency tracking.
0 dict[str, Any] 
def get_autodoc_stats(self) -> dict[str, Any]

Get statistics about autodoc dependency tracking.

Returns

dict[str, Any] —

Dictionary with tracking stats