# virtual_orchestrator URL: /api/autodoc/virtual_orchestrator/ Section: autodoc -------------------------------------------------------------------------------- virtual_orchestrator - Bengal window.BENGAL_THEME_DEFAULTS = { appearance: 'dark', palette: 'snow-lynx' }; // Progressive Enhancement System Configuration window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/bengal/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Try different keywords or check your spelling Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr ᓚᘏᗢ Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List ᓚᘏᗢ Magnifying Glass Search X Close Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal API Reference __main__ bengal Caret Right Folder Analysis community_detection graph_analysis graph_reporting graph_visualizer knowledge_graph link_suggestions link_types page_rank path_analysis performance_advisor results Caret Right Folder Assets manifest pipeline Caret Right Folder Autodoc base config docstring_parser utils virtual_orchestrator Caret Right Folder Extractors cli openapi python Caret Right Folder Models cli common openapi python Caret Right Folder Cache asset_dependency_map cache_store cacheable compression dependency_tracker page_discovery_cache query_index query_index_registry taxonomy_index utils Caret Right Folder Build Cache autodoc_tracking core file_tracking fingerprint parsed_content_cache rendered_output_cache taxonomy_index_mixin validation_cache Caret Right Folder Indexes author_index category_index date_range_index section_index Caret Right Folder Cli __main__ base site_templates utils Caret Right Folder Commands assets build clean collections config debug explain fix health init perf project serve site skeleton sources theme utils validate Caret Right Folder Graph __main__ bridges communities orphans pagerank report suggest Caret Right Folder New config presets scaffolds site wizard Caret Right Folder Helpers cli_app_loader cli_output config_validation error_handling menu_config metadata progress site_loader traceback validation Caret Right Folder Skeleton hydrator schema Caret Right Folder Templates base registry Caret Right Folder Blog template Caret Right Folder Changelog template Caret Right Folder Default template Caret Right Folder Docs template Caret Right Folder Landing template Caret Right Folder Portfolio template Caret Right Folder Resume template Caret Right Folder Collections errors loader schemas validator Caret Right Folder Config defaults deprecation directory_loader env_overrides environment feature_mappings hash loader merge origin_tracker validators Caret Right Folder Content Layer entry loaders manager source Caret Right Folder Sources github local notion rest Caret Right Folder Content Types base registry strategies Caret Right Folder Core build_context cascade_engine menu section theme Caret Right Folder Asset asset_core css_transforms Caret Right Folder Page computed content metadata navigation operations page_core proxy relationships utils Caret Right Folder Site core data discovery factories page_caches properties section_registry theme Caret Right Folder Debug base config_inspector content_migrator delta_analyzer dependency_visualizer explainer incremental_debugger models reporter shortcode_sandbox Caret Right Folder Discovery asset_discovery content_discovery Caret Right Folder Fonts downloader generator Caret Right Folder Health autofix base health_check report Caret Right Folder Linkcheck async_checker ignore_policy internal_checker models orchestrator Caret Right Folder Validators anchors assets cache config connectivity cross_ref fonts links menu navigation output performance rendering rss sitemap taxonomy tracks Caret Right Folder Directives analysis checkers constants Caret Right Folder Orchestration asset content full_to_incremental incremental menu postprocess related_posts render section static streaming taxonomy Caret Right Folder Postprocess html_output redirects rss sitemap special_pages Caret Right Folder Output Formats index_generator json_generator llm_generator lunr_index_generator txt_generator utils Caret Right Folder Rendering api_doc_enhancer asset_extractor errors jinja_utils link_transformer link_validator pygments_cache renderer template_context template_profiler validator Caret Right Folder Parsers base factory mistune native_html pygments_patch python_markdown Caret Right Folder Pipeline core output thread_local toc transforms Caret Right Folder Plugins badges cross_references inline_icon term variable_substitution Caret Right Folder Directives _icons admonitions badge base button cache cards checklist code_tabs container contracts data_table dropdown embed errors example_label fenced figure glossary icon include list_table literalinclude marimo navigation options rubric steps tabs target term terminal tokens utils validator video Caret Right Folder Template Engine asset_url core environment manifest menu url_helpers Caret Right Folder Template Functions advanced_collections advanced_strings autodoc collections content crossref data dates debug files get_page i18n icons images math_functions navigation pagination_helpers seo strings tables taxonomies theme urls Caret Right Folder Server build_handler component_preview constants dev_server live_reload pid_manager reload_controller request_handler request_logger resource_manager utils Caret Right Folder Services validation Caret Right Folder Themes config Caret Right Folder Utils atomic_write autodoc build_context build_stats build_summary cli_output css_minifier dates dotdict error_handlers file_io file_lock hashing incremental_constants js_bundler live_progress logger metadata observability page_initializer pagination path_resolver paths performance_collector performance_report profile progress retry rich_console sections swizzle text theme_registry theme_resolution thread_local traceback_config traceback_renderer url_normalization url_strategy API Reference Autodoc ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot 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 Caret Right 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 Caret Right def has_failures(self) -> bool Check if any failures occurred. Returns bool has_warnings Check if any warnings occurred. 0 bool Caret Right 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 Caret Right 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 Caret Right 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 Caret Right __init__ 7 None Caret Right 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 Caret Right def __repr__(self) -> str Returns str VirtualAutodocOrchestrator Orchestrate API documentation generation as virtual pages. This orchestrator creates virtual Page … 23 Caret Right 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 Caret Right 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… Caret Right 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 Caret Right __init__ Initialize virtual autodoc orchestrator. 1 None Caret Right 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 Caret Right 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 Caret Right 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 Caret Right 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] Caret Right 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] Caret Right 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] Caret Right 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… Caret Right 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: First pass: Create all Page objects and add them to sections 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 Caret Right 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 Caret Right 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] Caret Right 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 Caret Right 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 Caret Right 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 Caret Right 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 Caret Right 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] Caret Right 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 Caret Right 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 Caret Right 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] Caret Right def _extract_python(self) -> list[DocElement] Extract Python API documentation. Returns list[DocElement] _extract_cli Extract CLI documentation. 0 list[DocElement] Caret Right def _extract_cli(self) -> list[DocElement] Extract CLI documentation. Returns list[DocElement] _extract_openapi Extract OpenAPI documentation. 0 list[DocElement] Caret Right 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 Caret Right 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 ← Previous utils List © 2025 Bengal ᓚᘏᗢ window.BENGAL_LAZY_ASSETS = { tabulator: '/bengal/assets/js/tabulator.min.js', dataTable: '/bengal/assets/js/data-table.js', mermaidToolbar: '/bengal/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/bengal/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/bengal/assets/js/graph-minimap.cc7e42e3.js', graphContextual: '/bengal/assets/js/graph-contextual.440e59c6.js' }; window.BENGAL_ICONS = { close: '/bengal/assets/icons/close.911d4fe1.svg', enlarge: '/bengal/assets/icons/enlarge.652035e5.svg', copy: '/bengal/assets/icons/copy.3d56e945.svg', 'download-svg': '/bengal/assets/icons/download.04f07e1b.svg', 'download-png': '/bengal/assets/icons/image.c34dfd40.svg', 'zoom-in': '/bengal/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/bengal/assets/icons/zoom-out.38857c77.svg', reset: '/bengal/assets/icons/reset.d26dba29.svg' }; Arrow Up X -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 2451 - Reading Time: 12 minutes