1 line
230 KiB
JSON
1 line
230 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"docforge","text":"<ul> <li>Docforge</li> </ul>"},{"location":"#docforge","title":"docforge","text":""},{"location":"#docforge--summary","title":"Summary","text":"<p>Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).</p> <p><code>doc-forge</code> statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code.</p>"},{"location":"#docforge--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install doc-forge\n</code></pre>"},{"location":"#docforge--cli-usage","title":"CLI usage","text":"<p>Each site kind (<code>lib</code>, <code>api</code>, <code>wiki</code>) is built independently into <code>site/{kind}</code>.</p>"},{"location":"#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"<pre><code>doc-forge build --mkdocs --module my_package\n</code></pre>"},{"location":"#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"<pre><code>doc-forge build --api --openapi-spec spec.json\n</code></pre>"},{"location":"#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"<pre><code>doc-forge build --wiki --site-name my_package\n</code></pre>"},{"location":"#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"<pre><code>doc-forge build --mcp --module my_package\n</code></pre>"},{"location":"#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"<pre><code>doc-forge build --mcp --mkdocs --wiki --module my_package\n</code></pre> <p>Each enabled kind gets its own MkDocs config (<code>docs/mkdocs.{lib,api,wiki}.yml</code>) and its own site under <code>site/</code>.</p>"},{"location":"#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"<pre><code>doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n</code></pre>"},{"location":"#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"<pre><code>doc-forge serve --mcp --module my_package\n</code></pre>"},{"location":"#docforge--core-concepts","title":"Core concepts","text":""},{"location":"#docforge--loader","title":"Loader","text":"<p>Extracts symbols, signatures, and docstrings using static analysis.</p>"},{"location":"#docforge--semantic-model","title":"Semantic model","text":"<p>Structured, renderer-agnostic representation of the API.</p>"},{"location":"#docforge--renderer","title":"Renderer","text":"<p>Converts the semantic model into output formats such as MkDocs or MCP JSON.</p>"},{"location":"#docforge--symbol","title":"Symbol","text":"<p>Any documentable object</p> <ul> <li>module</li> <li>class</li> <li>function</li> <li>method</li> <li>property</li> <li>attribute</li> </ul>"},{"location":"#docforge--architecture","title":"Architecture","text":"<p><code>doc-forge</code> follows a compiler architecture:</p>"},{"location":"#docforge--front-end","title":"Front-end:","text":"<p>Static analysis of modules, classes, functions, type hints, and docstrings.</p>"},{"location":"#docforge--middle-end","title":"Middle-end:","text":"<p>Builds a semantic model describing symbols and relationships.</p>"},{"location":"#docforge--back-end","title":"Back-end:","text":"<p>Renders documentation using interchangeable renderers.</p> <p>This architecture ensures deterministic documentation generation.</p>"},{"location":"#docforge--rendering-pipeline","title":"Rendering pipeline","text":"<p>Typical flow:</p> <pre><code>Python package\n |\nLoader (static analysis)\n |\nSemantic model\n |\nRenderer\n |\nMkDocs site or MCP JSON\n</code></pre>"},{"location":"#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"<p>GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.</p> <ul> <li>Docstrings are the single source of truth.</li> <li><code>doc-forge</code> compiles docstrings but does not generate documentation content.</li> <li>Documentation follows the Python import hierarchy.</li> <li>Every public symbol should have a complete and accurate docstring.</li> </ul>"},{"location":"#docforge--general-rules","title":"General rules","text":"<ul> <li>Use Markdown headings at package and module level.</li> <li>Use Google-style structured sections at class, function, and method level.</li> <li>Use type hints in signatures.</li> <li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the signature types. This keeps docstrings self-contained and machine-parseable.</li> <li>Write summaries in imperative form.</li> <li>Sections are separated by <code>---</code></li> </ul>"},{"location":"#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"<p>Group related information using labeled subsections.</p> <p>Example:</p> <pre><code>Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n</code></pre>"},{"location":"#docforge--example-formatting","title":"Example formatting","text":"<ul> <li>Use indentation for examples.</li> <li>Indent section contents using four spaces.</li> <li>Use code blocks for example code.</li> </ul> Example <p>Single example:</p> <pre><code>Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n</code></pre> <p>Multiple examples:</p> <pre><code>Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n</code></pre> <p>Avoid fenced code blocks inside argument descriptions and other prose lines.</p> <p>Inside <code>Example:</code> sections, fenced <code>python</code> code blocks are allowed and must be indented four spaces, matching the examples below.</p>"},{"location":"#docforge--separator-rules","title":"Separator rules","text":"<p>Use horizontal separators only at docstring root level to separate sections:</p> <pre><code>---\n</code></pre> <p>Allowed locations:</p> <ul> <li>package docstrings</li> <li>module docstrings</li> <li>major documentation sections</li> </ul> <p>Do not use separators inside code sections.</p>"},{"location":"#docforge--package-docstrings","title":"Package docstrings","text":"<p>Package docstrings act as the documentation home page.</p> <p>Recommended sections:</p> <pre><code># Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n</code></pre> Example <p>Package Doc String:</p> <pre><code>'''\n# Summary\n\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n```bash\npip install foo-bar\n```\n\n---\n\n# Quick start\n\n```python\nfrom foobar import Foo, BarEngine\n\nfoo = Foo(\"example\")\nengine = BarEngine([foo])\n\nresult = engine.run()\n```\n\n---\n'''\n</code></pre>"},{"location":"#docforge--module-docstrings","title":"Module docstrings","text":"<p>Module docstrings describe a subsystem.</p> <p>Recommended sections:</p> <pre><code># Summary\n# Examples\n# Notes\n</code></pre> Example <p>Module Doc String:</p> <pre><code>'''\n# Summary\n\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n---\n'''\n</code></pre>"},{"location":"#docforge--class-docstrings","title":"Class docstrings","text":"<p>Class docstrings define object responsibility, lifecycle, and attributes.</p> <p>Recommended sections:</p> <pre><code>Attributes:\nNotes:\nExample:\nRaises:\n</code></pre> Example <p>Simple Foo:</p> <pre><code>class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n</code></pre> <p>Complex Bar:</p> <pre><code>class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n</code></pre>"},{"location":"#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"<p>Function docstrings define API contracts.</p> <p>Recommended sections:</p> <pre><code>Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n</code></pre> Example <p>Simple process method:</p> <pre><code>def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n</code></pre> <p>Multiple Examples:</p> <pre><code>def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n</code></pre>"},{"location":"#docforge--property-docstrings","title":"Property docstrings","text":"<p>Properties must document return values.</p> Example <p>Property Doc String:</p> <pre><code>```python\n@property\ndef foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n```\n</code></pre>"},{"location":"#docforge--attribute-documentation","title":"Attribute documentation","text":"<p>Document attributes in class docstrings using <code>Attributes:</code>.</p> Example <p>Attribute Doc String:</p> <pre><code>```python\n'''\nRepresents a processing stage.\n\nAttributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n'''\n```\n</code></pre>"},{"location":"#docforge--parsing-guarantees","title":"Parsing guarantees","text":"<p>GSDFC ensures doc-forge can deterministically extract:</p> <ul> <li>symbol kind (module, class, function, property, attribute)</li> <li>symbol name</li> <li>parameters</li> <li>return values</li> <li>attributes</li> <li>examples</li> <li>structured Notes subsections</li> </ul> <p>This enables:</p> <ul> <li>reliable MkDocs rendering</li> <li>deterministic MCP export</li> <li>accurate AI semantic interpretation</li> </ul> Notes <ul> <li>doc-forge never executes analyzed modules.</li> <li>Documentation is generated entirely through static analysis.</li> </ul>"},{"location":"#docforge-classes","title":"Classes","text":""},{"location":"#docforge.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"#docforge.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"#docforge.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"#docforge.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"#docforge-functions","title":"Functions","text":""},{"location":"#docforge.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"cli/#docforge.cli--summary","title":"Summary","text":"<p>Command line interface entry point for doc-forge.</p> <p>This module exposes the primary CLI entry function used by the <code>doc-forge</code> command. The actual command implementation resides in <code>docforge.cli.main</code>, while this module provides a stable import path for external tools and the package entry point configuration.</p> <p>The CLI is responsible for orchestrating documentation workflows such as generating renderer sources, building documentation sites, exporting machine-readable documentation bundles, and starting development or MCP servers.</p>"},{"location":"cli/#docforge.cli--typical-usage","title":"Typical usage","text":"<p>The CLI is normally invoked through the installed command:</p> <pre><code>doc-forge <command> [options]\n</code></pre> <p>Programmatic invocation is also possible:</p> <p>Example:</p> <pre><code>```python\nfrom docforge.cli import main\nmain()\n```\n</code></pre>"},{"location":"cli/api_utils/","title":"Api Utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"<p>Utilities for building API documentation from an OpenAPI specification.</p>"},{"location":"cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata <code>dataclass</code>","text":"<pre><code>OpenAPIMetadata(\n site_name: str,\n site_description: str | None,\n site_author: str | None,\n)\n</code></pre> <p>Metadata derived from the <code>info</code> block of an OpenAPI specification.</p> <p>Attributes:</p> Name Type Description <code>site_name</code> <code>str</code> <p>Spec title, used as the MkDocs site name.</p> <code>site_description</code> <code>str | None</code> <p>Spec description, used as the site description.</p> <code>site_author</code> <code>str | None</code> <p>Contact name (fallback: contact email), used as the site author.</p>"},{"location":"cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"<pre><code>derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n</code></pre> <p>Derive MkDocs site metadata from an OpenAPI spec <code>info</code> block.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>dict</code> <p>Parsed OpenAPI specification.</p> required <p>Returns:</p> Name Type Description <code>OpenAPIMetadata</code> <code>OpenAPIMetadata</code> <p>Site name, description, and author derived from the spec.</p>"},{"location":"cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"<pre><code>generate_api_sources(\n spec: dict[Any, Any], docs_dir: Path\n) -> None\n</code></pre> <p>Generate swagger-enabled Markdown sources and the spec copy.</p> <p>The specification is written as <code>openapi.json</code> inside <code>docs_dir</code> and an <code>index.md</code> embedding the swagger UI is generated alongside it.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>dict</code> <p>Parsed OpenAPI specification.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory (for example <code>docs/api</code>) where the swagger sources are written.</p> required"},{"location":"cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"<pre><code>load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n</code></pre> <p>Load and validate an OpenAPI specification from a JSON file.</p> <p>Parameters:</p> Name Type Description Default <code>spec_path</code> <code>Path</code> <p>Path to the OpenAPI JSON specification file.</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict[Any, Any]</code> <p>The parsed OpenAPI specification.</p> <p>Raises:</p> Type Description <code>ClickException</code> <p>If the file cannot be read or the <code>info</code> block is invalid.</p>"},{"location":"cli/commands/","title":"Commands","text":""},{"location":"cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"<p>Command definitions for the doc-forge CLI.</p> <p>Provides the CLI structure using Click, including build, serve, and tree commands.</p> Notes <ul> <li>The <code>build</code> command validates requested modes before generating anything.</li> <li><code>--mkdocs</code>, <code>--api</code>, and <code>--wiki</code> each emit their own MkDocs config and build (<code>docs/mkdocs.{kind}.yml</code> into <code>site/{kind}</code>); <code>--mcp</code> generates a machine-readable bundle independently.</li> </ul>"},{"location":"cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"cli/commands/#docforge.cli.commands.build","title":"build","text":"<pre><code>build(\n mcp: bool,\n mkdocs: bool,\n api: bool,\n wiki: bool,\n refresh: bool,\n module_is_source: bool,\n module: str | None,\n openapi_spec: Path | None,\n project_name: str | None,\n site_name: str | None,\n docs_dir: Path,\n wiki_dir: Path,\n nav_file: Path,\n template: Path | None,\n out_dir: Path,\n) -> None\n</code></pre> <p>Build documentation artifacts.</p> <p>This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.</p> <p>Depending on the selected options, the build can target:</p> <ul> <li>A lib MkDocs site (<code>--mkdocs</code>) for library reference docs</li> <li>A swagger-enabled API MkDocs site (<code>--api</code>) built from an OpenAPI spec</li> <li>A wiki MkDocs site (<code>--wiki</code>) built from hand-written markdown</li> <li>MCP structured documentation resources (<code>--mcp</code>)</li> </ul> <p>Each enabled site kind produces its own MkDocs configuration (<code>docs/mkdocs.{kind}.yml</code>) and its own build (<code>site/{kind}</code>).</p> Notes <ul> <li>At least one of <code>--mcp</code>, <code>--mkdocs</code>, <code>--wiki</code>, or <code>--api</code> must be provided.</li> <li><code>--mkdocs</code>, <code>--api</code>, and <code>--wiki</code> emit independent MkDocs builds, while <code>--mcp</code> emits a machine-readable bundle.</li> <li>Configuration files are generated only when absent; an existing <code>docs/mkdocs.{kind}.yml</code> is used as-is. Pass <code>--refresh</code> to rebaseline it from the templates.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>mcp</code> <code>bool</code> <p>Enable MCP documentation generation.</p> required <code>mkdocs</code> <code>bool</code> <p>Enable the lib MkDocs documentation generation.</p> required <code>api</code> <code>bool</code> <p>Enable API documentation generation from an OpenAPI spec.</p> required <code>wiki</code> <code>bool</code> <p>Build a hand-written wiki directory as its own MkDocs site.</p> required <code>refresh</code> <code>bool</code> <p>Regenerate <code>docs/mkdocs.{kind}.yml</code> from templates even when it already exists. By default, existing configs are used as-is.</p> required <code>module_is_source</code> <code>bool</code> <p>Treat the specified module directory as the project root.</p> required <code>module</code> <code>str | None</code> <p>Python module import path to document.</p> required <code>openapi_spec</code> <code>Path | None</code> <p>Path to the OpenAPI JSON specification used for API docs.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name.</p> required <code>site_name</code> <code>str | None</code> <p>Display name for the lib and wiki MkDocs sites.</p> required <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used for generated sources.</p> required <code>wiki_dir</code> <code>Path</code> <p>Directory containing hand-written wiki markdown files.</p> required <code>nav_file</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <code>template</code> <code>Path | None</code> <p>Optional custom MkDocs configuration template.</p> required <code>out_dir</code> <code>Path</code> <p>Output directory for generated MCP resources.</p> required <p>Raises:</p> Type Description <code>UsageError</code> <p>If required options are missing or conflicting.</p>"},{"location":"cli/commands/#docforge.cli.commands.serve","title":"serve","text":"<pre><code>serve(\n mcp: bool,\n mkdocs: bool,\n lib: bool,\n api: bool,\n wiki: bool,\n module: str | None,\n mkdocs_yml: Path,\n out_dir: Path,\n) -> None\n</code></pre> <p>Serve generated documentation locally.</p> <p>Depending on the selected mode, this command starts either:</p> <ul> <li>A MkDocs development server for browsing a site, or</li> <li>An MCP server exposing structured documentation resources</li> </ul> <p>The kind flags (<code>--lib</code>, <code>--api</code>, <code>--wiki</code>) select the generated per-kind config (<code>docs/mkdocs.{kind}.yml</code>); <code>--mkdocs</code> serves the config passed via <code>--mkdocs-yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>mcp</code> <code>bool</code> <p>Serve documentation using the MCP server.</p> required <code>mkdocs</code> <code>bool</code> <p>Serve the MkDocs development site from <code>--mkdocs-yml</code>.</p> required <code>lib</code> <code>bool</code> <p>Serve the lib MkDocs site.</p> required <code>api</code> <code>bool</code> <p>Serve the API MkDocs site.</p> required <code>wiki</code> <code>bool</code> <p>Serve the wiki MkDocs site.</p> required <code>module</code> <code>str | None</code> <p>Python module import path to serve via MCP.</p> required <code>mkdocs_yml</code> <code>Path</code> <p>Path to the MkDocs configuration file.</p> required <code>out_dir</code> <code>Path</code> <p>Root directory containing MCP documentation resources.</p> required <p>Raises:</p> Type Description <code>UsageError</code> <p>If invalid or conflicting options are provided.</p>"},{"location":"cli/commands/#docforge.cli.commands.tree","title":"tree","text":"<pre><code>tree(module: str, project_name: str | None) -> None\n</code></pre> <p>Display the documentation object tree for a module.</p> <p>This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path to introspect.</p> required <code>project_name</code> <code>str | None</code> <p>Optional name to display as the project root.</p> required"},{"location":"cli/main/","title":"Main","text":""},{"location":"cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"cli/main/#docforge.cli.main--summary","title":"Summary","text":"<p>Command-line entry point for the doc-forge CLI.</p> <p>This module exposes the executable entry point that initializes the Click command group defined in <code>docforge.cli.commands</code>.</p>"},{"location":"cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"cli/main/#docforge.cli.main.main","title":"main","text":"<pre><code>main() -> None\n</code></pre> <p>Run the doc-forge command-line interface.</p> <p>This function initializes and executes the Click CLI application. It is used as the console entry point when invoking <code>doc-forge</code> from the command line.</p>"},{"location":"cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"<p>Utilities for working with MCP in the doc-forge CLI.</p> Notes <ul> <li><code>generate_resources</code> produces the bundle consumed by <code>MCPServer</code>: <code>index.json</code>, <code>nav.json</code>, and per-module resources under <code>modules/</code>.</li> <li>Resource URIs use the <code>docs://</code> scheme: <code>docs://index</code>, <code>docs://nav</code>, and <code>docs://modules/{module}</code>.</li> </ul>"},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"<pre><code>generate_resources(\n module: str, project_name: str | None, out_dir: Path\n) -> None\n</code></pre> <p>Generate MCP documentation resources from a Python module.</p> <p>The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used as the entry point for documentation generation.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name used in generated documentation metadata.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources (index.json, nav.json, and module data) will be written.</p> required"},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"<pre><code>serve(module: str, mcp_root: Path) -> None\n</code></pre> <p>Start an MCP server for a pre-generated documentation bundle.</p> <p>The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used to identify the served documentation instance.</p> required <code>mcp_root</code> <code>Path</code> <p>Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If the MCP documentation bundle is missing required files or directories.</p>"},{"location":"cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"<p>Utilities for working with MkDocs in the doc-forge CLI.</p> Notes <ul> <li>A separate <code>mkdocs.{kind}.yml</code> configuration and build is emitted per enabled kind (lib, api, wiki), each scoped to its own <code>docs_dir</code> and written into its own <code>site_dir</code> (<code>site/lib</code>, <code>site/api</code>, <code>site/wiki</code>).</li> <li>Navigation blocks are re-rooted per kind: the wiki navigation drops its leading <code>wiki/</code> scope and the resolved nav spec drops its <code>lib/</code> scope.</li> </ul>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"<pre><code>build_configs(yml_paths: Iterable[Path]) -> None\n</code></pre> <p>Build the MkDocs documentation site for every given configuration.</p> <p>Each configuration file is loaded and built in turn, producing the per-kind static sites (<code>site/lib</code>, <code>site/api</code>, <code>site/wiki</code>).</p> <p>Parameters:</p> Name Type Description Default <code>yml_paths</code> <code>Iterable[Path]</code> <p>Configuration files to build, in order.</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If a configuration file does not exist.</p>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"<pre><code>build_lib_nav(\n nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n</code></pre> <p>Build the re-rooted navigation block for a lib site.</p> <p>The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the <code>lib</code> subdirectory by stripping its leading <code>lib/</code> scope component.</p> <p>Parameters:</p> Name Type Description Default <code>nav_file</code> <code>Path</code> <p>Path to the <code>docforge.nav.yml</code> navigation specification.</p> required <code>docs_root</code> <code>Path</code> <p>Shared documentation root containing the <code>lib</code> sources.</p> required <p>Returns:</p> Type Description <code>tuple[list[dict[str, Any]], dict[str, str] | None]</code> <p>tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.</p> <p>Raises:</p> Type Description <code>FileError</code> <p>If the navigation specification cannot be found.</p>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"<pre><code>build_wiki_nav_block(\n wiki_dir: Path,\n) -> list[dict[str, Any]]\n</code></pre> <p>Build the re-rooted navigation block for a wiki site.</p> <p>The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading <code>wiki/</code> scope component.</p> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries relative to the wiki directory.</p> <p>Raises:</p> Type Description <code>FileError</code> <p>If the wiki directory does not exist.</p>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"<pre><code>generate_site_config(\n kind: str,\n kind_root: Path,\n nav_block: list[dict[str, Any]],\n out: Path,\n site_name: str,\n docs_dir: str,\n site_dir: str,\n template: Path | None = None,\n site_description: str | None = None,\n site_author: str | None = None,\n theme_icon: dict[str, str] | None = None,\n) -> None\n</code></pre> <p>Generate a per-kind <code>mkdocs.{kind}.yml</code> configuration file.</p> <p>The configuration is created by merging the shared <code>mkdocs.common.yml</code> template with the fragment contributed by the kind (<code>lib</code>, <code>api</code>, or <code>wiki</code>). Both <code>docs_dir</code> and <code>site_dir</code> are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example <code>lib</code>) and the per-kind site output (for example <code>../site/lib</code>).</p> <p>Parameters:</p> Name Type Description Default <code>kind</code> <code>str</code> <p>Documentation kind, one of <code>lib</code>, <code>api</code>, or <code>wiki</code>.</p> required <code>kind_root</code> <code>Path</code> <p>Directory scoped to the kind (for example <code>docs/lib</code>) that serves as the MkDocs <code>docs_dir</code>.</p> required <code>nav_block</code> <code>list[dict[str, Any]]</code> <p>Re-rooted navigation entries for the kind's site.</p> required <code>out</code> <code>Path</code> <p>Destination path where the generated <code>mkdocs.{kind}.yml</code> file is written.</p> required <code>site_name</code> <code>str</code> <p>Display name for the generated documentation site.</p> required <code>docs_dir</code> <code>str</code> <p>MkDocs <code>docs_dir</code> value, relative to the configuration file's directory.</p> required <code>site_dir</code> <code>str</code> <p>MkDocs <code>site_dir</code> value, relative to the configuration file's directory.</p> required <code>template</code> <code>Path | None</code> <p>Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.</p> <code>None</code> <code>site_description</code> <code>str | None</code> <p>Optional site description written into the configuration.</p> <code>None</code> <code>site_author</code> <code>str | None</code> <p>Optional site author written into the configuration.</p> <code>None</code> <code>theme_icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries injected as <code>theme.icon</code>.</p> <code>None</code>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n module: str,\n docs_dir: Path,\n project_name: str | None = None,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate MkDocs Markdown sources for a Python module.</p> <p>This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used as the entry point for documentation generation.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory where the generated Markdown files will be written.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name used in documentation metadata.</p> <code>None</code> <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module directory as the project root rather than a nested module.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. If not provided, defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"<pre><code>load_spec_icon(nav_file: Path) -> dict[str, str] | None\n</code></pre> <p>Load the theme icon mapping from a navigation specification.</p> <p>Parameters:</p> Name Type Description Default <code>nav_file</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Type Description <code>dict[str, str] | None</code> <p>dict[str, str] | None: The icon mapping, or <code>None</code> when the specification file is absent or cannot be parsed.</p>"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"<pre><code>serve(mkdocs_yml: Path) -> None\n</code></pre> <p>Start an MkDocs development server with live reload.</p> <p>The server watches documentation files and automatically reloads the site when changes are detected.</p> <p>Parameters:</p> Name Type Description Default <code>mkdocs_yml</code> <code>Path</code> <p>Path to the <code>mkdocs.yml</code> configuration file.</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If the configuration file does not exist.</p>"},{"location":"docforge/","title":"Docforge","text":"<ul> <li>Cli</li> <li>Loaders</li> <li>Models</li> <li>Nav</li> <li>Renderers</li> <li>Servers</li> </ul>"},{"location":"docforge/#docforge","title":"docforge","text":""},{"location":"docforge/#docforge--summary","title":"Summary","text":"<p>Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).</p> <p><code>doc-forge</code> statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code.</p>"},{"location":"docforge/#docforge--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install doc-forge\n</code></pre>"},{"location":"docforge/#docforge--cli-usage","title":"CLI usage","text":"<p>Each site kind (<code>lib</code>, <code>api</code>, <code>wiki</code>) is built independently into <code>site/{kind}</code>.</p>"},{"location":"docforge/#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"<pre><code>doc-forge build --mkdocs --module my_package\n</code></pre>"},{"location":"docforge/#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"<pre><code>doc-forge build --api --openapi-spec spec.json\n</code></pre>"},{"location":"docforge/#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"<pre><code>doc-forge build --wiki --site-name my_package\n</code></pre>"},{"location":"docforge/#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"<pre><code>doc-forge build --mcp --module my_package\n</code></pre>"},{"location":"docforge/#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"<pre><code>doc-forge build --mcp --mkdocs --wiki --module my_package\n</code></pre> <p>Each enabled kind gets its own MkDocs config (<code>docs/mkdocs.{lib,api,wiki}.yml</code>) and its own site under <code>site/</code>.</p>"},{"location":"docforge/#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"<pre><code>doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n</code></pre>"},{"location":"docforge/#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"<pre><code>doc-forge serve --mcp --module my_package\n</code></pre>"},{"location":"docforge/#docforge--core-concepts","title":"Core concepts","text":""},{"location":"docforge/#docforge--loader","title":"Loader","text":"<p>Extracts symbols, signatures, and docstrings using static analysis.</p>"},{"location":"docforge/#docforge--semantic-model","title":"Semantic model","text":"<p>Structured, renderer-agnostic representation of the API.</p>"},{"location":"docforge/#docforge--renderer","title":"Renderer","text":"<p>Converts the semantic model into output formats such as MkDocs or MCP JSON.</p>"},{"location":"docforge/#docforge--symbol","title":"Symbol","text":"<p>Any documentable object</p> <ul> <li>module</li> <li>class</li> <li>function</li> <li>method</li> <li>property</li> <li>attribute</li> </ul>"},{"location":"docforge/#docforge--architecture","title":"Architecture","text":"<p><code>doc-forge</code> follows a compiler architecture:</p>"},{"location":"docforge/#docforge--front-end","title":"Front-end:","text":"<p>Static analysis of modules, classes, functions, type hints, and docstrings.</p>"},{"location":"docforge/#docforge--middle-end","title":"Middle-end:","text":"<p>Builds a semantic model describing symbols and relationships.</p>"},{"location":"docforge/#docforge--back-end","title":"Back-end:","text":"<p>Renders documentation using interchangeable renderers.</p> <p>This architecture ensures deterministic documentation generation.</p>"},{"location":"docforge/#docforge--rendering-pipeline","title":"Rendering pipeline","text":"<p>Typical flow:</p> <pre><code>Python package\n |\nLoader (static analysis)\n |\nSemantic model\n |\nRenderer\n |\nMkDocs site or MCP JSON\n</code></pre>"},{"location":"docforge/#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"<p>GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.</p> <ul> <li>Docstrings are the single source of truth.</li> <li><code>doc-forge</code> compiles docstrings but does not generate documentation content.</li> <li>Documentation follows the Python import hierarchy.</li> <li>Every public symbol should have a complete and accurate docstring.</li> </ul>"},{"location":"docforge/#docforge--general-rules","title":"General rules","text":"<ul> <li>Use Markdown headings at package and module level.</li> <li>Use Google-style structured sections at class, function, and method level.</li> <li>Use type hints in signatures.</li> <li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the signature types. This keeps docstrings self-contained and machine-parseable.</li> <li>Write summaries in imperative form.</li> <li>Sections are separated by <code>---</code></li> </ul>"},{"location":"docforge/#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"<p>Group related information using labeled subsections.</p> <p>Example:</p> <pre><code>Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n</code></pre>"},{"location":"docforge/#docforge--example-formatting","title":"Example formatting","text":"<ul> <li>Use indentation for examples.</li> <li>Indent section contents using four spaces.</li> <li>Use code blocks for example code.</li> </ul> Example <p>Single example:</p> <pre><code>Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n</code></pre> <p>Multiple examples:</p> <pre><code>Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n</code></pre> <p>Avoid fenced code blocks inside argument descriptions and other prose lines.</p> <p>Inside <code>Example:</code> sections, fenced <code>python</code> code blocks are allowed and must be indented four spaces, matching the examples below.</p>"},{"location":"docforge/#docforge--separator-rules","title":"Separator rules","text":"<p>Use horizontal separators only at docstring root level to separate sections:</p> <pre><code>---\n</code></pre> <p>Allowed locations:</p> <ul> <li>package docstrings</li> <li>module docstrings</li> <li>major documentation sections</li> </ul> <p>Do not use separators inside code sections.</p>"},{"location":"docforge/#docforge--package-docstrings","title":"Package docstrings","text":"<p>Package docstrings act as the documentation home page.</p> <p>Recommended sections:</p> <pre><code># Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n</code></pre> Example <p>Package Doc String:</p> <pre><code>'''\n# Summary\n\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n```bash\npip install foo-bar\n```\n\n---\n\n# Quick start\n\n```python\nfrom foobar import Foo, BarEngine\n\nfoo = Foo(\"example\")\nengine = BarEngine([foo])\n\nresult = engine.run()\n```\n\n---\n'''\n</code></pre>"},{"location":"docforge/#docforge--module-docstrings","title":"Module docstrings","text":"<p>Module docstrings describe a subsystem.</p> <p>Recommended sections:</p> <pre><code># Summary\n# Examples\n# Notes\n</code></pre> Example <p>Module Doc String:</p> <pre><code>'''\n# Summary\n\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n---\n'''\n</code></pre>"},{"location":"docforge/#docforge--class-docstrings","title":"Class docstrings","text":"<p>Class docstrings define object responsibility, lifecycle, and attributes.</p> <p>Recommended sections:</p> <pre><code>Attributes:\nNotes:\nExample:\nRaises:\n</code></pre> Example <p>Simple Foo:</p> <pre><code>class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n</code></pre> <p>Complex Bar:</p> <pre><code>class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n</code></pre>"},{"location":"docforge/#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"<p>Function docstrings define API contracts.</p> <p>Recommended sections:</p> <pre><code>Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n</code></pre> Example <p>Simple process method:</p> <pre><code>def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n</code></pre> <p>Multiple Examples:</p> <pre><code>def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n</code></pre>"},{"location":"docforge/#docforge--property-docstrings","title":"Property docstrings","text":"<p>Properties must document return values.</p> Example <p>Property Doc String:</p> <pre><code>```python\n@property\ndef foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n```\n</code></pre>"},{"location":"docforge/#docforge--attribute-documentation","title":"Attribute documentation","text":"<p>Document attributes in class docstrings using <code>Attributes:</code>.</p> Example <p>Attribute Doc String:</p> <pre><code>```python\n'''\nRepresents a processing stage.\n\nAttributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n'''\n```\n</code></pre>"},{"location":"docforge/#docforge--parsing-guarantees","title":"Parsing guarantees","text":"<p>GSDFC ensures doc-forge can deterministically extract:</p> <ul> <li>symbol kind (module, class, function, property, attribute)</li> <li>symbol name</li> <li>parameters</li> <li>return values</li> <li>attributes</li> <li>examples</li> <li>structured Notes subsections</li> </ul> <p>This enables:</p> <ul> <li>reliable MkDocs rendering</li> <li>deterministic MCP export</li> <li>accurate AI semantic interpretation</li> </ul> Notes <ul> <li>doc-forge never executes analyzed modules.</li> <li>Documentation is generated entirely through static analysis.</li> </ul>"},{"location":"docforge/#docforge-classes","title":"Classes","text":""},{"location":"docforge/#docforge.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"docforge/#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/#docforge.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"docforge/#docforge.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"docforge/#docforge.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"docforge/#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"docforge/#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"docforge/#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"docforge/#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"docforge/#docforge-functions","title":"Functions","text":""},{"location":"docforge/#docforge.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"docforge/cli/","title":"Cli","text":"<ul> <li>Api Utils</li> <li>Commands</li> <li>Main</li> <li>Mcp Utils</li> <li>Mkdocs Utils</li> </ul>"},{"location":"docforge/cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"docforge/cli/#docforge.cli--summary","title":"Summary","text":"<p>Command line interface entry point for doc-forge.</p> <p>This module exposes the primary CLI entry function used by the <code>doc-forge</code> command. The actual command implementation resides in <code>docforge.cli.main</code>, while this module provides a stable import path for external tools and the package entry point configuration.</p> <p>The CLI is responsible for orchestrating documentation workflows such as generating renderer sources, building documentation sites, exporting machine-readable documentation bundles, and starting development or MCP servers.</p>"},{"location":"docforge/cli/#docforge.cli--typical-usage","title":"Typical usage","text":"<p>The CLI is normally invoked through the installed command:</p> <pre><code>doc-forge <command> [options]\n</code></pre> <p>Programmatic invocation is also possible:</p> <p>Example:</p> <pre><code>```python\nfrom docforge.cli import main\nmain()\n```\n</code></pre>"},{"location":"docforge/cli/api_utils/","title":"Api Utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"<p>Utilities for building API documentation from an OpenAPI specification.</p>"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata <code>dataclass</code>","text":"<pre><code>OpenAPIMetadata(\n site_name: str,\n site_description: str | None,\n site_author: str | None,\n)\n</code></pre> <p>Metadata derived from the <code>info</code> block of an OpenAPI specification.</p> <p>Attributes:</p> Name Type Description <code>site_name</code> <code>str</code> <p>Spec title, used as the MkDocs site name.</p> <code>site_description</code> <code>str | None</code> <p>Spec description, used as the site description.</p> <code>site_author</code> <code>str | None</code> <p>Contact name (fallback: contact email), used as the site author.</p>"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"<pre><code>derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n</code></pre> <p>Derive MkDocs site metadata from an OpenAPI spec <code>info</code> block.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>dict</code> <p>Parsed OpenAPI specification.</p> required <p>Returns:</p> Name Type Description <code>OpenAPIMetadata</code> <code>OpenAPIMetadata</code> <p>Site name, description, and author derived from the spec.</p>"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"<pre><code>generate_api_sources(\n spec: dict[Any, Any], docs_dir: Path\n) -> None\n</code></pre> <p>Generate swagger-enabled Markdown sources and the spec copy.</p> <p>The specification is written as <code>openapi.json</code> inside <code>docs_dir</code> and an <code>index.md</code> embedding the swagger UI is generated alongside it.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>dict</code> <p>Parsed OpenAPI specification.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory (for example <code>docs/api</code>) where the swagger sources are written.</p> required"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"<pre><code>load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n</code></pre> <p>Load and validate an OpenAPI specification from a JSON file.</p> <p>Parameters:</p> Name Type Description Default <code>spec_path</code> <code>Path</code> <p>Path to the OpenAPI JSON specification file.</p> required <p>Returns:</p> Name Type Description <code>dict</code> <code>dict[Any, Any]</code> <p>The parsed OpenAPI specification.</p> <p>Raises:</p> Type Description <code>ClickException</code> <p>If the file cannot be read or the <code>info</code> block is invalid.</p>"},{"location":"docforge/cli/commands/","title":"Commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"<p>Command definitions for the doc-forge CLI.</p> <p>Provides the CLI structure using Click, including build, serve, and tree commands.</p> Notes <ul> <li>The <code>build</code> command validates requested modes before generating anything.</li> <li><code>--mkdocs</code>, <code>--api</code>, and <code>--wiki</code> each emit their own MkDocs config and build (<code>docs/mkdocs.{kind}.yml</code> into <code>site/{kind}</code>); <code>--mcp</code> generates a machine-readable bundle independently.</li> </ul>"},{"location":"docforge/cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands.build","title":"build","text":"<pre><code>build(\n mcp: bool,\n mkdocs: bool,\n api: bool,\n wiki: bool,\n refresh: bool,\n module_is_source: bool,\n module: str | None,\n openapi_spec: Path | None,\n project_name: str | None,\n site_name: str | None,\n docs_dir: Path,\n wiki_dir: Path,\n nav_file: Path,\n template: Path | None,\n out_dir: Path,\n) -> None\n</code></pre> <p>Build documentation artifacts.</p> <p>This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.</p> <p>Depending on the selected options, the build can target:</p> <ul> <li>A lib MkDocs site (<code>--mkdocs</code>) for library reference docs</li> <li>A swagger-enabled API MkDocs site (<code>--api</code>) built from an OpenAPI spec</li> <li>A wiki MkDocs site (<code>--wiki</code>) built from hand-written markdown</li> <li>MCP structured documentation resources (<code>--mcp</code>)</li> </ul> <p>Each enabled site kind produces its own MkDocs configuration (<code>docs/mkdocs.{kind}.yml</code>) and its own build (<code>site/{kind}</code>).</p> Notes <ul> <li>At least one of <code>--mcp</code>, <code>--mkdocs</code>, <code>--wiki</code>, or <code>--api</code> must be provided.</li> <li><code>--mkdocs</code>, <code>--api</code>, and <code>--wiki</code> emit independent MkDocs builds, while <code>--mcp</code> emits a machine-readable bundle.</li> <li>Configuration files are generated only when absent; an existing <code>docs/mkdocs.{kind}.yml</code> is used as-is. Pass <code>--refresh</code> to rebaseline it from the templates.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>mcp</code> <code>bool</code> <p>Enable MCP documentation generation.</p> required <code>mkdocs</code> <code>bool</code> <p>Enable the lib MkDocs documentation generation.</p> required <code>api</code> <code>bool</code> <p>Enable API documentation generation from an OpenAPI spec.</p> required <code>wiki</code> <code>bool</code> <p>Build a hand-written wiki directory as its own MkDocs site.</p> required <code>refresh</code> <code>bool</code> <p>Regenerate <code>docs/mkdocs.{kind}.yml</code> from templates even when it already exists. By default, existing configs are used as-is.</p> required <code>module_is_source</code> <code>bool</code> <p>Treat the specified module directory as the project root.</p> required <code>module</code> <code>str | None</code> <p>Python module import path to document.</p> required <code>openapi_spec</code> <code>Path | None</code> <p>Path to the OpenAPI JSON specification used for API docs.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name.</p> required <code>site_name</code> <code>str | None</code> <p>Display name for the lib and wiki MkDocs sites.</p> required <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used for generated sources.</p> required <code>wiki_dir</code> <code>Path</code> <p>Directory containing hand-written wiki markdown files.</p> required <code>nav_file</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <code>template</code> <code>Path | None</code> <p>Optional custom MkDocs configuration template.</p> required <code>out_dir</code> <code>Path</code> <p>Output directory for generated MCP resources.</p> required <p>Raises:</p> Type Description <code>UsageError</code> <p>If required options are missing or conflicting.</p>"},{"location":"docforge/cli/commands/#docforge.cli.commands.serve","title":"serve","text":"<pre><code>serve(\n mcp: bool,\n mkdocs: bool,\n lib: bool,\n api: bool,\n wiki: bool,\n module: str | None,\n mkdocs_yml: Path,\n out_dir: Path,\n) -> None\n</code></pre> <p>Serve generated documentation locally.</p> <p>Depending on the selected mode, this command starts either:</p> <ul> <li>A MkDocs development server for browsing a site, or</li> <li>An MCP server exposing structured documentation resources</li> </ul> <p>The kind flags (<code>--lib</code>, <code>--api</code>, <code>--wiki</code>) select the generated per-kind config (<code>docs/mkdocs.{kind}.yml</code>); <code>--mkdocs</code> serves the config passed via <code>--mkdocs-yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>mcp</code> <code>bool</code> <p>Serve documentation using the MCP server.</p> required <code>mkdocs</code> <code>bool</code> <p>Serve the MkDocs development site from <code>--mkdocs-yml</code>.</p> required <code>lib</code> <code>bool</code> <p>Serve the lib MkDocs site.</p> required <code>api</code> <code>bool</code> <p>Serve the API MkDocs site.</p> required <code>wiki</code> <code>bool</code> <p>Serve the wiki MkDocs site.</p> required <code>module</code> <code>str | None</code> <p>Python module import path to serve via MCP.</p> required <code>mkdocs_yml</code> <code>Path</code> <p>Path to the MkDocs configuration file.</p> required <code>out_dir</code> <code>Path</code> <p>Root directory containing MCP documentation resources.</p> required <p>Raises:</p> Type Description <code>UsageError</code> <p>If invalid or conflicting options are provided.</p>"},{"location":"docforge/cli/commands/#docforge.cli.commands.tree","title":"tree","text":"<pre><code>tree(module: str, project_name: str | None) -> None\n</code></pre> <p>Display the documentation object tree for a module.</p> <p>This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path to introspect.</p> required <code>project_name</code> <code>str | None</code> <p>Optional name to display as the project root.</p> required"},{"location":"docforge/cli/main/","title":"Main","text":""},{"location":"docforge/cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"docforge/cli/main/#docforge.cli.main--summary","title":"Summary","text":"<p>Command-line entry point for the doc-forge CLI.</p> <p>This module exposes the executable entry point that initializes the Click command group defined in <code>docforge.cli.commands</code>.</p>"},{"location":"docforge/cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"docforge/cli/main/#docforge.cli.main.main","title":"main","text":"<pre><code>main() -> None\n</code></pre> <p>Run the doc-forge command-line interface.</p> <p>This function initializes and executes the Click CLI application. It is used as the console entry point when invoking <code>doc-forge</code> from the command line.</p>"},{"location":"docforge/cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"<p>Utilities for working with MCP in the doc-forge CLI.</p> Notes <ul> <li><code>generate_resources</code> produces the bundle consumed by <code>MCPServer</code>: <code>index.json</code>, <code>nav.json</code>, and per-module resources under <code>modules/</code>.</li> <li>Resource URIs use the <code>docs://</code> scheme: <code>docs://index</code>, <code>docs://nav</code>, and <code>docs://modules/{module}</code>.</li> </ul>"},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"<pre><code>generate_resources(\n module: str, project_name: str | None, out_dir: Path\n) -> None\n</code></pre> <p>Generate MCP documentation resources from a Python module.</p> <p>The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used as the entry point for documentation generation.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name used in generated documentation metadata.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources (index.json, nav.json, and module data) will be written.</p> required"},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"<pre><code>serve(module: str, mcp_root: Path) -> None\n</code></pre> <p>Start an MCP server for a pre-generated documentation bundle.</p> <p>The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used to identify the served documentation instance.</p> required <code>mcp_root</code> <code>Path</code> <p>Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If the MCP documentation bundle is missing required files or directories.</p>"},{"location":"docforge/cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"<p>Utilities for working with MkDocs in the doc-forge CLI.</p> Notes <ul> <li>A separate <code>mkdocs.{kind}.yml</code> configuration and build is emitted per enabled kind (lib, api, wiki), each scoped to its own <code>docs_dir</code> and written into its own <code>site_dir</code> (<code>site/lib</code>, <code>site/api</code>, <code>site/wiki</code>).</li> <li>Navigation blocks are re-rooted per kind: the wiki navigation drops its leading <code>wiki/</code> scope and the resolved nav spec drops its <code>lib/</code> scope.</li> </ul>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"<pre><code>build_configs(yml_paths: Iterable[Path]) -> None\n</code></pre> <p>Build the MkDocs documentation site for every given configuration.</p> <p>Each configuration file is loaded and built in turn, producing the per-kind static sites (<code>site/lib</code>, <code>site/api</code>, <code>site/wiki</code>).</p> <p>Parameters:</p> Name Type Description Default <code>yml_paths</code> <code>Iterable[Path]</code> <p>Configuration files to build, in order.</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If a configuration file does not exist.</p>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"<pre><code>build_lib_nav(\n nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n</code></pre> <p>Build the re-rooted navigation block for a lib site.</p> <p>The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the <code>lib</code> subdirectory by stripping its leading <code>lib/</code> scope component.</p> <p>Parameters:</p> Name Type Description Default <code>nav_file</code> <code>Path</code> <p>Path to the <code>docforge.nav.yml</code> navigation specification.</p> required <code>docs_root</code> <code>Path</code> <p>Shared documentation root containing the <code>lib</code> sources.</p> required <p>Returns:</p> Type Description <code>tuple[list[dict[str, Any]], dict[str, str] | None]</code> <p>tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.</p> <p>Raises:</p> Type Description <code>FileError</code> <p>If the navigation specification cannot be found.</p>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"<pre><code>build_wiki_nav_block(\n wiki_dir: Path,\n) -> list[dict[str, Any]]\n</code></pre> <p>Build the re-rooted navigation block for a wiki site.</p> <p>The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading <code>wiki/</code> scope component.</p> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries relative to the wiki directory.</p> <p>Raises:</p> Type Description <code>FileError</code> <p>If the wiki directory does not exist.</p>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"<pre><code>generate_site_config(\n kind: str,\n kind_root: Path,\n nav_block: list[dict[str, Any]],\n out: Path,\n site_name: str,\n docs_dir: str,\n site_dir: str,\n template: Path | None = None,\n site_description: str | None = None,\n site_author: str | None = None,\n theme_icon: dict[str, str] | None = None,\n) -> None\n</code></pre> <p>Generate a per-kind <code>mkdocs.{kind}.yml</code> configuration file.</p> <p>The configuration is created by merging the shared <code>mkdocs.common.yml</code> template with the fragment contributed by the kind (<code>lib</code>, <code>api</code>, or <code>wiki</code>). Both <code>docs_dir</code> and <code>site_dir</code> are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example <code>lib</code>) and the per-kind site output (for example <code>../site/lib</code>).</p> <p>Parameters:</p> Name Type Description Default <code>kind</code> <code>str</code> <p>Documentation kind, one of <code>lib</code>, <code>api</code>, or <code>wiki</code>.</p> required <code>kind_root</code> <code>Path</code> <p>Directory scoped to the kind (for example <code>docs/lib</code>) that serves as the MkDocs <code>docs_dir</code>.</p> required <code>nav_block</code> <code>list[dict[str, Any]]</code> <p>Re-rooted navigation entries for the kind's site.</p> required <code>out</code> <code>Path</code> <p>Destination path where the generated <code>mkdocs.{kind}.yml</code> file is written.</p> required <code>site_name</code> <code>str</code> <p>Display name for the generated documentation site.</p> required <code>docs_dir</code> <code>str</code> <p>MkDocs <code>docs_dir</code> value, relative to the configuration file's directory.</p> required <code>site_dir</code> <code>str</code> <p>MkDocs <code>site_dir</code> value, relative to the configuration file's directory.</p> required <code>template</code> <code>Path | None</code> <p>Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.</p> <code>None</code> <code>site_description</code> <code>str | None</code> <p>Optional site description written into the configuration.</p> <code>None</code> <code>site_author</code> <code>str | None</code> <p>Optional site author written into the configuration.</p> <code>None</code> <code>theme_icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries injected as <code>theme.icon</code>.</p> <code>None</code>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n module: str,\n docs_dir: Path,\n project_name: str | None = None,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate MkDocs Markdown sources for a Python module.</p> <p>This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>str</code> <p>Python module import path used as the entry point for documentation generation.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory where the generated Markdown files will be written.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name used in documentation metadata.</p> <code>None</code> <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module directory as the project root rather than a nested module.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. If not provided, defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"<pre><code>load_spec_icon(nav_file: Path) -> dict[str, str] | None\n</code></pre> <p>Load the theme icon mapping from a navigation specification.</p> <p>Parameters:</p> Name Type Description Default <code>nav_file</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Type Description <code>dict[str, str] | None</code> <p>dict[str, str] | None: The icon mapping, or <code>None</code> when the specification file is absent or cannot be parsed.</p>"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"<pre><code>serve(mkdocs_yml: Path) -> None\n</code></pre> <p>Start an MkDocs development server with live reload.</p> <p>The server watches documentation files and automatically reloads the site when changes are detected.</p> <p>Parameters:</p> Name Type Description Default <code>mkdocs_yml</code> <code>Path</code> <p>Path to the <code>mkdocs.yml</code> configuration file.</p> required <p>Raises:</p> Type Description <code>ClickException</code> <p>If the configuration file does not exist.</p>"},{"location":"docforge/loaders/","title":"Loaders","text":"<ul> <li>Griffe Loader</li> </ul>"},{"location":"docforge/loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"docforge/loaders/#docforge.loaders--summary","title":"Summary","text":"<p>Loader layer for doc-forge.</p> <p>The <code>docforge.loaders</code> package is responsible for discovering Python modules and extracting documentation data using static analysis.</p>"},{"location":"docforge/loaders/#docforge.loaders--overview","title":"Overview","text":"<p>This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.</p> <p>Core capabilities include:</p> <ul> <li>Module discovery \u2013 Locate Python modules and packages within a project.</li> <li>Static introspection \u2013 Parse docstrings, signatures, and object hierarchies using the <code>griffe</code> library without executing the code.</li> <li>Public API filtering \u2013 Exclude private members (names prefixed with <code>_</code>) to produce clean public documentation structures.</li> </ul>"},{"location":"docforge/loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"docforge/loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"docforge/loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"<p>Utilities for loading and introspecting Python modules using Griffe.</p> <p>This module provides the <code>GriffeLoader</code> class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models.</p> Notes <ul> <li>All analysis is static; analyzed modules are never executed.</li> <li>Private members (names starting with <code>_</code>) are skipped during conversion.</li> </ul>"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"docforge/models/","title":"Models","text":"<ul> <li>Module</li> <li>Object</li> <li>Project</li> </ul>"},{"location":"docforge/models/#docforge.models","title":"docforge.models","text":""},{"location":"docforge/models/#docforge.models--summary","title":"Summary","text":"<p>Model layer for doc-forge.</p> <p>The <code>docforge.models</code> package defines the core data structures used to represent Python source code as a structured documentation model.</p>"},{"location":"docforge/models/#docforge.models--overview","title":"Overview","text":"<p>The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.</p> <p>Key components:</p> <ul> <li>Project \u2013 Root container representing an entire documented codebase.</li> <li>Module \u2013 Representation of a Python module or package containing documented members.</li> <li>DocObject \u2013 Recursive structure representing Python objects such as classes, functions, methods, and attributes.</li> </ul> <p>These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).</p>"},{"location":"docforge/models/#docforge.models-classes","title":"Classes","text":""},{"location":"docforge/models/#docforge.models.DocObject","title":"DocObject","text":"<pre><code>DocObject(\n name: str,\n kind: str,\n path: str,\n signature: str | None = None,\n docstring: str | None = None,\n)\n</code></pre> <p>Representation of a documented Python object.</p> <p>A <code>DocObject</code> models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Local name of the object.</p> <code>kind</code> <code>str</code> <p>Type of object (for example <code>class</code>, <code>function</code>, <code>method</code>, or <code>attribute</code>).</p> <code>path</code> <code>str</code> <p>Fully qualified dotted path to the object.</p> <code>signature</code> <code>str | None</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>str | None</code> <p>Raw docstring text extracted from the source code.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of member names to child <code>DocObject</code> instances.</p> <p>Initialize a DocObject instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Local name of the object.</p> required <code>kind</code> <code>str</code> <p>Object type identifier (for example <code>class</code> or <code>function</code>).</p> required <code>path</code> <code>str</code> <p>Fully qualified dotted path of the object.</p> required <code>signature</code> <code>str | None</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>str | None</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"docforge/models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.DocObject.add_member","title":"add_member","text":"<pre><code>add_member(obj: DocObject) -> None\n</code></pre> <p>Add a child documentation object.</p> <p>This is typically used when attaching methods to classes or nested objects to their parent containers.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to add as a member.</p> required"},{"location":"docforge/models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"<pre><code>get_all_members() -> Iterable[DocObject]\n</code></pre> <p>Return all child members of the object.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing nested members.</p>"},{"location":"docforge/models/#docforge.models.DocObject.get_member","title":"get_member","text":"<pre><code>get_member(name: str) -> DocObject\n</code></pre> <p>Retrieve a member object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the member to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the member does not exist.</p>"},{"location":"docforge/models/#docforge.models.Module","title":"Module","text":"<pre><code>Module(path: str, docstring: str | None = None)\n</code></pre> <p>Representation of a documented Python module or package.</p> <p>A <code>Module</code> stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.</p> <p>Attributes:</p> Name Type Description <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> <code>docstring</code> <code>str | None</code> <p>Module-level documentation string, if present.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of object names to their corresponding <code>DocObject</code> representations.</p> <p>Initialize a Module instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path identifying the module.</p> required <code>docstring</code> <code>str | None</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"docforge/models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Module.add_object","title":"add_object","text":"<pre><code>add_object(obj: DocObject) -> None\n</code></pre> <p>Add a documented object to the module.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to register as a top-level member of the module.</p> required"},{"location":"docforge/models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"<pre><code>get_all_objects() -> Iterable[DocObject]\n</code></pre> <p>Return all top-level documentation objects in the module.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing the module's public members.</p>"},{"location":"docforge/models/#docforge.models.Module.get_object","title":"get_object","text":"<pre><code>get_object(name: str) -> DocObject\n</code></pre> <p>Retrieve a documented object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the object to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If no object with the given name exists.</p>"},{"location":"docforge/models/#docforge.models.Project","title":"Project","text":"<pre><code>Project(name: str)\n</code></pre> <p>Representation of a documentation project.</p> <p>A <code>Project</code> serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Name of the project.</p> <code>modules</code> <code>dict[str, Module]</code> <p>Mapping of module paths to <code>Module</code> instances.</p> <p>Initialize a Project instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name used to identify the documentation project.</p> required Example <p>Create a project and register a module:</p> <pre><code>```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n</code></pre>"},{"location":"docforge/models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Project.add_module","title":"add_module","text":"<pre><code>add_module(module: Module) -> None\n</code></pre> <p>Register a module in the project.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>Module</code> <p>Module instance to add to the project.</p> required"},{"location":"docforge/models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"<pre><code>get_all_modules() -> Iterable[Module]\n</code></pre> <p>Return all modules contained in the project.</p> <p>Returns:</p> Type Description <code>Iterable[Module]</code> <p>Iterable[Module]: An iterable of <code>Module</code> instances.</p>"},{"location":"docforge/models/#docforge.models.Project.get_module","title":"get_module","text":"<pre><code>get_module(path: str) -> Module\n</code></pre> <p>Retrieve a module by its dotted path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Fully qualified dotted module path (for example <code>pkg.module</code>).</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>The corresponding <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the module does not exist in the project.</p>"},{"location":"docforge/models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"<pre><code>get_module_list() -> list[str]\n</code></pre> <p>Return the list of module import paths.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the dotted paths of all modules in the project.</p>"},{"location":"docforge/models/module/","title":"Module","text":""},{"location":"docforge/models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"docforge/models/module/#docforge.models.module--summary","title":"Summary","text":"<p>Documentation model representing a Python module or package.</p> <p>This module defines the <code>Module</code> class used in the doc-forge documentation model. A <code>Module</code> acts as a container for top-level documented objects (classes, functions, variables, and other members) discovered during introspection.</p> Notes <ul> <li>Only public members are stored; private names are filtered by the loader.</li> </ul>"},{"location":"docforge/models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"docforge/models/module/#docforge.models.module.Module","title":"Module","text":"<pre><code>Module(path: str, docstring: str | None = None)\n</code></pre> <p>Representation of a documented Python module or package.</p> <p>A <code>Module</code> stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.</p> <p>Attributes:</p> Name Type Description <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> <code>docstring</code> <code>str | None</code> <p>Module-level documentation string, if present.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of object names to their corresponding <code>DocObject</code> representations.</p> <p>Initialize a Module instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path identifying the module.</p> required <code>docstring</code> <code>str | None</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"docforge/models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"docforge/models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"<pre><code>add_object(obj: DocObject) -> None\n</code></pre> <p>Add a documented object to the module.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to register as a top-level member of the module.</p> required"},{"location":"docforge/models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"<pre><code>get_all_objects() -> Iterable[DocObject]\n</code></pre> <p>Return all top-level documentation objects in the module.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing the module's public members.</p>"},{"location":"docforge/models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"<pre><code>get_object(name: str) -> DocObject\n</code></pre> <p>Retrieve a documented object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the object to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If no object with the given name exists.</p>"},{"location":"docforge/models/object/","title":"Object","text":""},{"location":"docforge/models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"docforge/models/object/#docforge.models.object--summary","title":"Summary","text":"<p>Documentation model representing individual Python objects.</p> <p>This module defines the <code>DocObject</code> class, the fundamental recursive unit of the doc-forge documentation model. Each <code>DocObject</code> represents a Python entity such as a class, function, method, or attribute, and may contain nested members that form a hierarchical documentation structure.</p> Notes <ul> <li><code>DocObject</code> instances form a tree mirroring the Python import hierarchy.</li> <li>Objects are renderer-agnostic and may be consumed by any renderer.</li> </ul>"},{"location":"docforge/models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject","title":"DocObject","text":"<pre><code>DocObject(\n name: str,\n kind: str,\n path: str,\n signature: str | None = None,\n docstring: str | None = None,\n)\n</code></pre> <p>Representation of a documented Python object.</p> <p>A <code>DocObject</code> models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Local name of the object.</p> <code>kind</code> <code>str</code> <p>Type of object (for example <code>class</code>, <code>function</code>, <code>method</code>, or <code>attribute</code>).</p> <code>path</code> <code>str</code> <p>Fully qualified dotted path to the object.</p> <code>signature</code> <code>str | None</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>str | None</code> <p>Raw docstring text extracted from the source code.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of member names to child <code>DocObject</code> instances.</p> <p>Initialize a DocObject instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Local name of the object.</p> required <code>kind</code> <code>str</code> <p>Object type identifier (for example <code>class</code> or <code>function</code>).</p> required <code>path</code> <code>str</code> <p>Fully qualified dotted path of the object.</p> required <code>signature</code> <code>str | None</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>str | None</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"docforge/models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"<pre><code>add_member(obj: DocObject) -> None\n</code></pre> <p>Add a child documentation object.</p> <p>This is typically used when attaching methods to classes or nested objects to their parent containers.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to add as a member.</p> required"},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"<pre><code>get_all_members() -> Iterable[DocObject]\n</code></pre> <p>Return all child members of the object.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing nested members.</p>"},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"<pre><code>get_member(name: str) -> DocObject\n</code></pre> <p>Retrieve a member object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the member to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the member does not exist.</p>"},{"location":"docforge/models/project/","title":"Project","text":""},{"location":"docforge/models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"docforge/models/project/#docforge.models.project--summary","title":"Summary","text":"<p>Documentation model representing a project.</p> <p>This module defines the <code>Project</code> class, the top-level container used by doc-forge to represent a documented codebase. A <code>Project</code> aggregates multiple modules and provides access to them through a unified interface.</p> Notes <ul> <li>Modules are keyed by their dotted import path.</li> <li>Objects are renderer-agnostic; the same model feeds every renderer.</li> </ul>"},{"location":"docforge/models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"docforge/models/project/#docforge.models.project.Project","title":"Project","text":"<pre><code>Project(name: str)\n</code></pre> <p>Representation of a documentation project.</p> <p>A <code>Project</code> serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Name of the project.</p> <code>modules</code> <code>dict[str, Module]</code> <p>Mapping of module paths to <code>Module</code> instances.</p> <p>Initialize a Project instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name used to identify the documentation project.</p> required Example <p>Create a project and register a module:</p> <pre><code>```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n</code></pre>"},{"location":"docforge/models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"docforge/models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"<pre><code>add_module(module: Module) -> None\n</code></pre> <p>Register a module in the project.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>Module</code> <p>Module instance to add to the project.</p> required"},{"location":"docforge/models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"<pre><code>get_all_modules() -> Iterable[Module]\n</code></pre> <p>Return all modules contained in the project.</p> <p>Returns:</p> Type Description <code>Iterable[Module]</code> <p>Iterable[Module]: An iterable of <code>Module</code> instances.</p>"},{"location":"docforge/models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"<pre><code>get_module(path: str) -> Module\n</code></pre> <p>Retrieve a module by its dotted path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Fully qualified dotted module path (for example <code>pkg.module</code>).</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>The corresponding <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the module does not exist in the project.</p>"},{"location":"docforge/models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"<pre><code>get_module_list() -> list[str]\n</code></pre> <p>Return the list of module import paths.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the dotted paths of all modules in the project.</p>"},{"location":"docforge/nav/","title":"Nav","text":"<ul> <li>Mkdocs</li> <li>Resolver</li> <li>Spec</li> <li>Wiki</li> </ul>"},{"location":"docforge/nav/#docforge.nav","title":"docforge.nav","text":"<p>Navigation layer for doc-forge.</p> <p>The <code>docforge.nav</code> package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.</p>"},{"location":"docforge/nav/#docforge.nav--workflow","title":"Workflow","text":"<ol> <li>Specification \u2013 Users define navigation intent in <code>docforge.nav.yml</code>.</li> <li>Resolution \u2013 <code>resolve_nav</code> expands patterns and matches them against generated Markdown files.</li> <li>Emission \u2013 <code>MkDocsNavEmitter</code> converts the resolved structure into the YAML navigation format required by <code>mkdocs.yml</code>.</li> </ol> <p>This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.</p>"},{"location":"docforge/nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"<p>Emit MkDocs navigation structures from resolved navigation data.</p> <p>The emitter transforms a <code>ResolvedNav</code> object into the YAML-compatible list structure expected by the MkDocs <code>nav</code> configuration field.</p>"},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"<pre><code>emit(nav: ResolvedNav) -> list[dict[str, Any]]\n</code></pre> <p>Generate a navigation structure for <code>mkdocs.yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>nav</code> <code>ResolvedNav</code> <p>Resolved navigation data describing documentation groups and their associated Markdown files.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.</p>"},{"location":"docforge/nav/#docforge.nav.NavSpec","title":"NavSpec","text":"<pre><code>NavSpec(\n home: str | None,\n groups: dict[str, list[str]],\n icon: dict[str, str] | None = None,\n)\n</code></pre> <p>Parsed representation of a navigation specification.</p> <p>A <code>NavSpec</code> describes the intended documentation navigation layout before it is resolved against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page (for example <code>index.md</code>).</p> <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of navigation group titles to lists of file patterns or glob expressions.</p> <code>icon</code> <p>Optional mapping of theme icon entries (for example <code>{\"logo\": \"material/code-tags\"}</code>) injected into the MkDocs theme as <code>theme.icon</code>.</p> <p>Initialize a NavSpec instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home document.</p> required <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of group names to lists of path patterns (glob expressions).</p> required <code>icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries applied to the generated MkDocs configuration.</p> <code>None</code>"},{"location":"docforge/nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"<pre><code>all_patterns() -> list[str]\n</code></pre> <p>Return all path patterns referenced by the specification.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the home document (if defined) and all group pattern entries.</p>"},{"location":"docforge/nav/#docforge.nav.NavSpec.load","title":"load <code>classmethod</code>","text":"<pre><code>load(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Filesystem path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed configuration.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified file does not exist.</p> <code>ValueError</code> <p>If the file contents are not a valid navigation specification.</p>"},{"location":"docforge/nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"<pre><code>ResolvedNav(\n home: str | None,\n groups: dict[str, list[Path]],\n docs_root: Path | None = None,\n)\n</code></pre> <p>Resolved navigation structure.</p> <p>A <code>ResolvedNav</code> represents navigation data after glob patterns have been expanded and paths validated against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page.</p> <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of navigation group titles to lists of resolved documentation file paths.</p> <p>Initialize a ResolvedNav instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home page within the documentation root.</p> required <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of group titles to resolved documentation file paths.</p> required <code>docs_root</code> <code>Path | None</code> <p>Root directory of the documentation source files.</p> <code>None</code>"},{"location":"docforge/nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"<pre><code>all_files() -> Iterable[Path]\n</code></pre> <p>Iterate over all files referenced by the navigation structure.</p> <p>Yields:</p> Name Type Description <code>Path</code> <code>Iterable[Path]</code> <p>A documentation file referenced by the navigation, including the home page when defined.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the home page is defined but the documentation root is not available for resolution.</p>"},{"location":"docforge/nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"<pre><code>build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n</code></pre> <p>Derive an MkDocs navigation block from a wiki directory.</p> <p>Returned paths are relative to the parent of <code>wiki_dir</code> and carry the wiki directory name as their leading component (for example <code>wiki/01_overview.md</code> when the wiki lives at <code>docs/wiki</code>). This makes the result directly usable in an MkDocs <code>nav</code> block with</p> <ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries compatible with the MkDocs <code>nav</code> configuration. The list is empty if the wiki contains no Markdown files.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the wiki directory does not exist.</p>"},{"location":"docforge/nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"<pre><code>load_nav_spec(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification file.</p> <p>This helper function reads a YAML navigation file and constructs a corresponding <code>NavSpec</code> instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed specification.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specification file does not exist.</p> <code>ValueError</code> <p>If the YAML structure is invalid.</p>"},{"location":"docforge/nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"<pre><code>resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n</code></pre> <p>Resolve a navigation specification against the filesystem.</p> <p>The function expands glob patterns defined in a <code>NavSpec</code> and verifies that referenced documentation files exist within the documentation root.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>NavSpec</code> <p>Navigation specification describing documentation layout.</p> required <code>docs_root</code> <code>Path</code> <p>Root directory containing documentation Markdown files.</p> required <p>Returns:</p> Name Type Description <code>ResolvedNav</code> <code>ResolvedNav</code> <p>A <code>ResolvedNav</code> instance containing validated navigation paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the documentation root does not exist or a navigation pattern does not match any files.</p>"},{"location":"docforge/nav/mkdocs/","title":"Mkdocs","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"<p>MkDocs navigation emitter.</p> <p>This module provides the <code>MkDocsNavEmitter</code> class, which converts a <code>ResolvedNav</code> instance into the navigation structure required by the MkDocs <code>nav</code> configuration.</p> Notes <ul> <li>The emitted structure is a list of dictionaries, one per top-level nav entry, matching the MkDocs <code>nav</code> YAML format.</li> </ul>"},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"<p>Emit MkDocs navigation structures from resolved navigation data.</p> <p>The emitter transforms a <code>ResolvedNav</code> object into the YAML-compatible list structure expected by the MkDocs <code>nav</code> configuration field.</p>"},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"<pre><code>emit(nav: ResolvedNav) -> list[dict[str, Any]]\n</code></pre> <p>Generate a navigation structure for <code>mkdocs.yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>nav</code> <code>ResolvedNav</code> <p>Resolved navigation data describing documentation groups and their associated Markdown files.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.</p>"},{"location":"docforge/nav/resolver/","title":"Resolver","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"<p>Navigation resolution utilities.</p> <p>This module resolves a <code>NavSpec</code> against the filesystem by expanding glob patterns and validating that referenced documentation files exist.</p> Notes <ul> <li>Glob resolution is recursive and returns paths in sorted order.</li> <li>Unmatched patterns raise <code>FileNotFoundError</code> to fail fast on typos.</li> </ul>"},{"location":"docforge/nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"<pre><code>ResolvedNav(\n home: str | None,\n groups: dict[str, list[Path]],\n docs_root: Path | None = None,\n)\n</code></pre> <p>Resolved navigation structure.</p> <p>A <code>ResolvedNav</code> represents navigation data after glob patterns have been expanded and paths validated against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page.</p> <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of navigation group titles to lists of resolved documentation file paths.</p> <p>Initialize a ResolvedNav instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home page within the documentation root.</p> required <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of group titles to resolved documentation file paths.</p> required <code>docs_root</code> <code>Path | None</code> <p>Root directory of the documentation source files.</p> <code>None</code>"},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"<pre><code>all_files() -> Iterable[Path]\n</code></pre> <p>Iterate over all files referenced by the navigation structure.</p> <p>Yields:</p> Name Type Description <code>Path</code> <code>Iterable[Path]</code> <p>A documentation file referenced by the navigation, including the home page when defined.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the home page is defined but the documentation root is not available for resolution.</p>"},{"location":"docforge/nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"<pre><code>resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n</code></pre> <p>Resolve a navigation specification against the filesystem.</p> <p>The function expands glob patterns defined in a <code>NavSpec</code> and verifies that referenced documentation files exist within the documentation root.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>NavSpec</code> <p>Navigation specification describing documentation layout.</p> required <code>docs_root</code> <code>Path</code> <p>Root directory containing documentation Markdown files.</p> required <p>Returns:</p> Name Type Description <code>ResolvedNav</code> <code>ResolvedNav</code> <p>A <code>ResolvedNav</code> instance containing validated navigation paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the documentation root does not exist or a navigation pattern does not match any files.</p>"},{"location":"docforge/nav/spec/","title":"Spec","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"<p>Navigation specification model.</p> <p>This module defines the <code>NavSpec</code> class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically <code>docforge.nav.yml</code>).</p> Notes <ul> <li>The spec file supports an optional <code>icon</code> mapping for MkDocs theme customization.</li> <li>All file references in <code>groups</code> are relative to the documentation root.</li> </ul>"},{"location":"docforge/nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"<pre><code>NavSpec(\n home: str | None,\n groups: dict[str, list[str]],\n icon: dict[str, str] | None = None,\n)\n</code></pre> <p>Parsed representation of a navigation specification.</p> <p>A <code>NavSpec</code> describes the intended documentation navigation layout before it is resolved against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page (for example <code>index.md</code>).</p> <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of navigation group titles to lists of file patterns or glob expressions.</p> <code>icon</code> <p>Optional mapping of theme icon entries (for example <code>{\"logo\": \"material/code-tags\"}</code>) injected into the MkDocs theme as <code>theme.icon</code>.</p> <p>Initialize a NavSpec instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home document.</p> required <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of group names to lists of path patterns (glob expressions).</p> required <code>icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries applied to the generated MkDocs configuration.</p> <code>None</code>"},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"<pre><code>all_patterns() -> list[str]\n</code></pre> <p>Return all path patterns referenced by the specification.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the home document (if defined) and all group pattern entries.</p>"},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.load","title":"load <code>classmethod</code>","text":"<pre><code>load(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Filesystem path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed configuration.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified file does not exist.</p> <code>ValueError</code> <p>If the file contents are not a valid navigation specification.</p>"},{"location":"docforge/nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"<pre><code>load_nav_spec(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification file.</p> <p>This helper function reads a YAML navigation file and constructs a corresponding <code>NavSpec</code> instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed specification.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specification file does not exist.</p> <code>ValueError</code> <p>If the YAML structure is invalid.</p>"},{"location":"docforge/nav/wiki/","title":"Wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"<p>Wiki navigation derivation.</p> <p>This module provides <code>build_wiki_nav</code>, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically <code>docs/wiki</code>). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.</p>"},{"location":"docforge/nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":"<ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul>"},{"location":"docforge/nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"<pre><code>build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n</code></pre> <p>Derive an MkDocs navigation block from a wiki directory.</p> <p>Returned paths are relative to the parent of <code>wiki_dir</code> and carry the wiki directory name as their leading component (for example <code>wiki/01_overview.md</code> when the wiki lives at <code>docs/wiki</code>). This makes the result directly usable in an MkDocs <code>nav</code> block with</p> <ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries compatible with the MkDocs <code>nav</code> configuration. The list is empty if the wiki contains no Markdown files.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the wiki directory does not exist.</p>"},{"location":"docforge/renderers/","title":"Renderers","text":"<ul> <li>Base</li> <li>Mcp Renderer</li> <li>Mkdocs Renderer</li> </ul>"},{"location":"docforge/renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"docforge/renderers/#docforge.renderers--summary","title":"Summary","text":"<p>Renderers layer for doc-forge.</p> <p>The <code>docforge.renderers</code> package transforms the internal documentation models into files formatted for specific documentation systems.</p>"},{"location":"docforge/renderers/#docforge.renderers--overview","title":"Overview","text":"<p>Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.</p> <p>Current implementations:</p> <ul> <li>MkDocsRenderer \u2013 Produces Markdown files compatible with MkDocs and the <code>mkdocstrings</code> plugin. It automatically handles package hierarchy and generates <code>index.md</code> files for packages.</li> <li>MCPRenderer \u2013 Emits structured JSON resources designed for consumption by Model Context Protocol (MCP) clients.</li> </ul>"},{"location":"docforge/renderers/#docforge.renderers--extending","title":"Extending","text":"<p>New renderers can be added by implementing the <code>DocRenderer</code> protocol defined in <code>docforge.renderers.base</code>.</p>"},{"location":"docforge/renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"docforge/renderers/base/","title":"Base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"<p>Renderer base interfaces and configuration models.</p> <p>This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the <code>DocRenderer</code> protocol.</p>"},{"location":"docforge/renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"<p> Bases: <code>Protocol</code></p> <p>Protocol defining the interface for documentation renderers.</p> <p>Implementations of this protocol are responsible for transforming a <code>Project</code> model into renderer-specific documentation sources.</p>"},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate renderer-specific documentation sources.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules and documentation objects.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated documentation sources should be written.</p> required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"<pre><code>RendererConfig(out_dir: Path, project: Project)\n</code></pre> <p>Configuration container for documentation renderers.</p> <p>A <code>RendererConfig</code> instance groups together the project model and the output directory used during rendering.</p> <p>Attributes:</p> Name Type Description <code>out_dir</code> <code>Path</code> <p>Directory where generated documentation files will be written.</p> <code>project</code> <code>Project</code> <p>Documentation project model to be rendered.</p> <p>Initialize a RendererConfig instance.</p> <p>Parameters:</p> Name Type Description Default <code>out_dir</code> <code>Path</code> <p>Target directory where documentation files should be written.</p> required <code>project</code> <code>Project</code> <p>Introspected project model to render.</p> required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"<p>MCP renderer implementation.</p> <p>This module defines the <code>MCPRenderer</code> class, which generates documentation resources compatible with the Model Context Protocol (MCP).</p>"},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"docforge/renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"<p>MkDocs renderer implementation.</p> <p>This module defines the <code>MkDocsRenderer</code> class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.</p> <p>The renderer ensures a consistent documentation structure by:</p> <ul> <li>Creating a root <code>index.md</code> if one does not exist</li> <li>Generating package index pages automatically</li> <li>Linking child modules within parent package pages</li> <li>Optionally generating <code>README.md</code> from the root package docstring</li> </ul>"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"docforge/servers/","title":"Servers","text":"<ul> <li>Mcp Server</li> </ul>"},{"location":"docforge/servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"docforge/servers/#docforge.servers--summary","title":"Summary","text":"<p>Server layer for doc-forge.</p> <p>This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.</p>"},{"location":"docforge/servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer","title":"MCPServer","text":"<pre><code>MCPServer(mcp_root: Path, name: str)\n</code></pre> <p>MCP server for serving a pre-generated documentation bundle.</p> <p>The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.</p> <p>Attributes:</p> Name Type Description <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle.</p> <code>app</code> <code>FastMCP</code> <p>Underlying FastMCP application instance that registers resources and tools.</p> <p>Initialize the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle (for example <code>index.json</code>, <code>nav.json</code>, and <code>modules/</code>).</p> required <code>name</code> <code>str</code> <p>Identifier used for the MCP server instance.</p> required"},{"location":"docforge/servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer.run","title":"run","text":"<pre><code>run(\n transport: Literal[\n \"stdio\", \"sse\", \"streamable-http\"\n ] = \"streamable-http\",\n) -> None\n</code></pre> <p>Start the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>transport</code> <code>Literal['stdio', 'sse', 'streamable-http']</code> <p>Transport mechanism used by the MCP server. Supported options include <code>stdio</code>, <code>sse</code>, and <code>streamable-http</code>.</p> <code>'streamable-http'</code>"},{"location":"docforge/servers/mcp_server/","title":"Mcp Server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"<p>MCP server implementation.</p> <p>This module defines the <code>MCPServer</code> class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).</p> Notes <ul> <li>The served bundle is generated offline by <code>MCPRenderer</code>.</li> <li>Missing resources are reported as structured error dictionaries rather than raising exceptions.</li> <li>The server exposes read-only resources and a single health-check tool.</li> </ul>"},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"<pre><code>MCPServer(mcp_root: Path, name: str)\n</code></pre> <p>MCP server for serving a pre-generated documentation bundle.</p> <p>The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.</p> <p>Attributes:</p> Name Type Description <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle.</p> <code>app</code> <code>FastMCP</code> <p>Underlying FastMCP application instance that registers resources and tools.</p> <p>Initialize the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle (for example <code>index.json</code>, <code>nav.json</code>, and <code>modules/</code>).</p> required <code>name</code> <code>str</code> <p>Identifier used for the MCP server instance.</p> required"},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"<pre><code>run(\n transport: Literal[\n \"stdio\", \"sse\", \"streamable-http\"\n ] = \"streamable-http\",\n) -> None\n</code></pre> <p>Start the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>transport</code> <code>Literal['stdio', 'sse', 'streamable-http']</code> <p>Transport mechanism used by the MCP server. Supported options include <code>stdio</code>, <code>sse</code>, and <code>streamable-http</code>.</p> <code>'streamable-http'</code>"},{"location":"loaders/","title":"Loaders","text":""},{"location":"loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"loaders/#docforge.loaders--summary","title":"Summary","text":"<p>Loader layer for doc-forge.</p> <p>The <code>docforge.loaders</code> package is responsible for discovering Python modules and extracting documentation data using static analysis.</p>"},{"location":"loaders/#docforge.loaders--overview","title":"Overview","text":"<p>This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.</p> <p>Core capabilities include:</p> <ul> <li>Module discovery \u2013 Locate Python modules and packages within a project.</li> <li>Static introspection \u2013 Parse docstrings, signatures, and object hierarchies using the <code>griffe</code> library without executing the code.</li> <li>Public API filtering \u2013 Exclude private members (names prefixed with <code>_</code>) to produce clean public documentation structures.</li> </ul>"},{"location":"loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"<p>Utilities for loading and introspecting Python modules using Griffe.</p> <p>This module provides the <code>GriffeLoader</code> class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models.</p> Notes <ul> <li>All analysis is static; analyzed modules are never executed.</li> <li>Private members (names starting with <code>_</code>) are skipped during conversion.</li> </ul>"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"<pre><code>GriffeLoader()\n</code></pre> <p>Load Python modules using Griffe and convert them into doc-forge models.</p> <p>This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into <code>Project</code>, <code>Module</code>, and <code>DocObject</code> instances used by doc-forge.</p> <p>Attributes:</p> Name Type Description <code>_loader</code> <code>GriffeLoader</code> <p>Internal Griffe loader with dedicated module and line collections.</p> <p>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"<pre><code>load_module(path: str) -> Module\n</code></pre> <p>Load and convert a single Python module.</p> <p>The module is introspected using Griffe and then transformed into a doc-forge <code>Module</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>A populated <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>ImportError</code> <p>If the module cannot be loaded by Griffe.</p> <code>KeyError</code> <p>If the loaded module is missing from the module collection.</p> Example <p>Load a single module:</p> <pre><code>```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n</code></pre>"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"<pre><code>load_project(\n module_paths: list[str],\n project_name: str | None = None,\n skip_import_errors: bool | None = None,\n) -> Project\n</code></pre> <p>Load multiple modules and assemble them into a Project model.</p> <p>Each module path is introspected and converted into a <code>Module</code> instance. All modules are then aggregated into a single <code>Project</code> object.</p> <p>Parameters:</p> Name Type Description Default <code>module_paths</code> <code>list[str]</code> <p>List of dotted module import paths to load.</p> required <code>project_name</code> <code>str | None</code> <p>Optional override for the project name. Defaults to the top-level name of the first module.</p> <code>None</code> <code>skip_import_errors</code> <code>bool | None</code> <p>If True, modules that fail to load will be skipped instead of raising an error.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Project</code> <code>Project</code> <p>A populated <code>Project</code> instance containing the loaded modules.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If no module paths are provided.</p> <code>ImportError</code> <p>If a module fails to load and <code>skip_import_errors</code> is False.</p>"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"<pre><code>discover_module_paths(\n module_name: str, project_root: Path | None = None\n) -> list[str]\n</code></pre> <p>Discover Python modules within a package directory.</p> <p>The function scans the filesystem for <code>.py</code> files inside the specified package and converts them into dotted module import paths.</p> <p>Discovery rules:</p> <ul> <li>Directories containing <code>__init__.py</code> are treated as packages.</li> <li>Each <code>.py</code> file is treated as a module.</li> <li>Results are returned as dotted import paths.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>module_name</code> <code>str</code> <p>Top-level package name to discover modules from.</p> required <code>project_root</code> <code>Path | None</code> <p>Root directory used to resolve module paths. If not provided, the current working directory is used.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A sorted list of unique dotted module import paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified package directory does not exist.</p>"},{"location":"models/","title":"Models","text":""},{"location":"models/#docforge.models","title":"docforge.models","text":""},{"location":"models/#docforge.models--summary","title":"Summary","text":"<p>Model layer for doc-forge.</p> <p>The <code>docforge.models</code> package defines the core data structures used to represent Python source code as a structured documentation model.</p>"},{"location":"models/#docforge.models--overview","title":"Overview","text":"<p>The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.</p> <p>Key components:</p> <ul> <li>Project \u2013 Root container representing an entire documented codebase.</li> <li>Module \u2013 Representation of a Python module or package containing documented members.</li> <li>DocObject \u2013 Recursive structure representing Python objects such as classes, functions, methods, and attributes.</li> </ul> <p>These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).</p>"},{"location":"models/#docforge.models-classes","title":"Classes","text":""},{"location":"models/#docforge.models.DocObject","title":"DocObject","text":"<pre><code>DocObject(\n name: str,\n kind: str,\n path: str,\n signature: str | None = None,\n docstring: str | None = None,\n)\n</code></pre> <p>Representation of a documented Python object.</p> <p>A <code>DocObject</code> models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Local name of the object.</p> <code>kind</code> <code>str</code> <p>Type of object (for example <code>class</code>, <code>function</code>, <code>method</code>, or <code>attribute</code>).</p> <code>path</code> <code>str</code> <p>Fully qualified dotted path to the object.</p> <code>signature</code> <code>str | None</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>str | None</code> <p>Raw docstring text extracted from the source code.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of member names to child <code>DocObject</code> instances.</p> <p>Initialize a DocObject instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Local name of the object.</p> required <code>kind</code> <code>str</code> <p>Object type identifier (for example <code>class</code> or <code>function</code>).</p> required <code>path</code> <code>str</code> <p>Fully qualified dotted path of the object.</p> required <code>signature</code> <code>str | None</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>str | None</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"models/#docforge.models.DocObject.add_member","title":"add_member","text":"<pre><code>add_member(obj: DocObject) -> None\n</code></pre> <p>Add a child documentation object.</p> <p>This is typically used when attaching methods to classes or nested objects to their parent containers.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to add as a member.</p> required"},{"location":"models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"<pre><code>get_all_members() -> Iterable[DocObject]\n</code></pre> <p>Return all child members of the object.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing nested members.</p>"},{"location":"models/#docforge.models.DocObject.get_member","title":"get_member","text":"<pre><code>get_member(name: str) -> DocObject\n</code></pre> <p>Retrieve a member object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the member to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the member does not exist.</p>"},{"location":"models/#docforge.models.Module","title":"Module","text":"<pre><code>Module(path: str, docstring: str | None = None)\n</code></pre> <p>Representation of a documented Python module or package.</p> <p>A <code>Module</code> stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.</p> <p>Attributes:</p> Name Type Description <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> <code>docstring</code> <code>str | None</code> <p>Module-level documentation string, if present.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of object names to their corresponding <code>DocObject</code> representations.</p> <p>Initialize a Module instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path identifying the module.</p> required <code>docstring</code> <code>str | None</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Module.add_object","title":"add_object","text":"<pre><code>add_object(obj: DocObject) -> None\n</code></pre> <p>Add a documented object to the module.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to register as a top-level member of the module.</p> required"},{"location":"models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"<pre><code>get_all_objects() -> Iterable[DocObject]\n</code></pre> <p>Return all top-level documentation objects in the module.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing the module's public members.</p>"},{"location":"models/#docforge.models.Module.get_object","title":"get_object","text":"<pre><code>get_object(name: str) -> DocObject\n</code></pre> <p>Retrieve a documented object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the object to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If no object with the given name exists.</p>"},{"location":"models/#docforge.models.Project","title":"Project","text":"<pre><code>Project(name: str)\n</code></pre> <p>Representation of a documentation project.</p> <p>A <code>Project</code> serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Name of the project.</p> <code>modules</code> <code>dict[str, Module]</code> <p>Mapping of module paths to <code>Module</code> instances.</p> <p>Initialize a Project instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name used to identify the documentation project.</p> required Example <p>Create a project and register a module:</p> <pre><code>```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n</code></pre>"},{"location":"models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Project.add_module","title":"add_module","text":"<pre><code>add_module(module: Module) -> None\n</code></pre> <p>Register a module in the project.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>Module</code> <p>Module instance to add to the project.</p> required"},{"location":"models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"<pre><code>get_all_modules() -> Iterable[Module]\n</code></pre> <p>Return all modules contained in the project.</p> <p>Returns:</p> Type Description <code>Iterable[Module]</code> <p>Iterable[Module]: An iterable of <code>Module</code> instances.</p>"},{"location":"models/#docforge.models.Project.get_module","title":"get_module","text":"<pre><code>get_module(path: str) -> Module\n</code></pre> <p>Retrieve a module by its dotted path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Fully qualified dotted module path (for example <code>pkg.module</code>).</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>The corresponding <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the module does not exist in the project.</p>"},{"location":"models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"<pre><code>get_module_list() -> list[str]\n</code></pre> <p>Return the list of module import paths.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the dotted paths of all modules in the project.</p>"},{"location":"models/module/","title":"Module","text":""},{"location":"models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"models/module/#docforge.models.module--summary","title":"Summary","text":"<p>Documentation model representing a Python module or package.</p> <p>This module defines the <code>Module</code> class used in the doc-forge documentation model. A <code>Module</code> acts as a container for top-level documented objects (classes, functions, variables, and other members) discovered during introspection.</p> Notes <ul> <li>Only public members are stored; private names are filtered by the loader.</li> </ul>"},{"location":"models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"models/module/#docforge.models.module.Module","title":"Module","text":"<pre><code>Module(path: str, docstring: str | None = None)\n</code></pre> <p>Representation of a documented Python module or package.</p> <p>A <code>Module</code> stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.</p> <p>Attributes:</p> Name Type Description <code>path</code> <code>str</code> <p>Dotted import path of the module.</p> <code>docstring</code> <code>str | None</code> <p>Module-level documentation string, if present.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of object names to their corresponding <code>DocObject</code> representations.</p> <p>Initialize a Module instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dotted import path identifying the module.</p> required <code>docstring</code> <code>str | None</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"<pre><code>add_object(obj: DocObject) -> None\n</code></pre> <p>Add a documented object to the module.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to register as a top-level member of the module.</p> required"},{"location":"models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"<pre><code>get_all_objects() -> Iterable[DocObject]\n</code></pre> <p>Return all top-level documentation objects in the module.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing the module's public members.</p>"},{"location":"models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"<pre><code>get_object(name: str) -> DocObject\n</code></pre> <p>Retrieve a documented object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the object to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If no object with the given name exists.</p>"},{"location":"models/object/","title":"Object","text":""},{"location":"models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"models/object/#docforge.models.object--summary","title":"Summary","text":"<p>Documentation model representing individual Python objects.</p> <p>This module defines the <code>DocObject</code> class, the fundamental recursive unit of the doc-forge documentation model. Each <code>DocObject</code> represents a Python entity such as a class, function, method, or attribute, and may contain nested members that form a hierarchical documentation structure.</p> Notes <ul> <li><code>DocObject</code> instances form a tree mirroring the Python import hierarchy.</li> <li>Objects are renderer-agnostic and may be consumed by any renderer.</li> </ul>"},{"location":"models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"models/object/#docforge.models.object.DocObject","title":"DocObject","text":"<pre><code>DocObject(\n name: str,\n kind: str,\n path: str,\n signature: str | None = None,\n docstring: str | None = None,\n)\n</code></pre> <p>Representation of a documented Python object.</p> <p>A <code>DocObject</code> models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Local name of the object.</p> <code>kind</code> <code>str</code> <p>Type of object (for example <code>class</code>, <code>function</code>, <code>method</code>, or <code>attribute</code>).</p> <code>path</code> <code>str</code> <p>Fully qualified dotted path to the object.</p> <code>signature</code> <code>str | None</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>str | None</code> <p>Raw docstring text extracted from the source code.</p> <code>members</code> <code>dict[str, DocObject]</code> <p>Mapping of member names to child <code>DocObject</code> instances.</p> <p>Initialize a DocObject instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Local name of the object.</p> required <code>kind</code> <code>str</code> <p>Object type identifier (for example <code>class</code> or <code>function</code>).</p> required <code>path</code> <code>str</code> <p>Fully qualified dotted path of the object.</p> required <code>signature</code> <code>str | None</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>str | None</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"<pre><code>add_member(obj: DocObject) -> None\n</code></pre> <p>Add a child documentation object.</p> <p>This is typically used when attaching methods to classes or nested objects to their parent containers.</p> <p>Parameters:</p> Name Type Description Default <code>obj</code> <code>DocObject</code> <p>Documentation object to add as a member.</p> required"},{"location":"models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"<pre><code>get_all_members() -> Iterable[DocObject]\n</code></pre> <p>Return all child members of the object.</p> <p>Returns:</p> Type Description <code>Iterable[DocObject]</code> <p>Iterable[DocObject]: An iterable of <code>DocObject</code> instances representing nested members.</p>"},{"location":"models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"<pre><code>get_member(name: str) -> DocObject\n</code></pre> <p>Retrieve a member object by name.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name of the member to retrieve.</p> required <p>Returns:</p> Name Type Description <code>DocObject</code> <code>DocObject</code> <p>The corresponding <code>DocObject</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the member does not exist.</p>"},{"location":"models/project/","title":"Project","text":""},{"location":"models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"models/project/#docforge.models.project--summary","title":"Summary","text":"<p>Documentation model representing a project.</p> <p>This module defines the <code>Project</code> class, the top-level container used by doc-forge to represent a documented codebase. A <code>Project</code> aggregates multiple modules and provides access to them through a unified interface.</p> Notes <ul> <li>Modules are keyed by their dotted import path.</li> <li>Objects are renderer-agnostic; the same model feeds every renderer.</li> </ul>"},{"location":"models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"models/project/#docforge.models.project.Project","title":"Project","text":"<pre><code>Project(name: str)\n</code></pre> <p>Representation of a documentation project.</p> <p>A <code>Project</code> serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.</p> <p>Attributes:</p> Name Type Description <code>name</code> <code>str</code> <p>Name of the project.</p> <code>modules</code> <code>dict[str, Module]</code> <p>Mapping of module paths to <code>Module</code> instances.</p> <p>Initialize a Project instance.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>Name used to identify the documentation project.</p> required Example <p>Create a project and register a module:</p> <pre><code>```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n</code></pre>"},{"location":"models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"<pre><code>add_module(module: Module) -> None\n</code></pre> <p>Register a module in the project.</p> <p>Parameters:</p> Name Type Description Default <code>module</code> <code>Module</code> <p>Module instance to add to the project.</p> required"},{"location":"models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"<pre><code>get_all_modules() -> Iterable[Module]\n</code></pre> <p>Return all modules contained in the project.</p> <p>Returns:</p> Type Description <code>Iterable[Module]</code> <p>Iterable[Module]: An iterable of <code>Module</code> instances.</p>"},{"location":"models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"<pre><code>get_module(path: str) -> Module\n</code></pre> <p>Retrieve a module by its dotted path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Fully qualified dotted module path (for example <code>pkg.module</code>).</p> required <p>Returns:</p> Name Type Description <code>Module</code> <code>Module</code> <p>The corresponding <code>Module</code> instance.</p> <p>Raises:</p> Type Description <code>KeyError</code> <p>If the module does not exist in the project.</p>"},{"location":"models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"<pre><code>get_module_list() -> list[str]\n</code></pre> <p>Return the list of module import paths.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the dotted paths of all modules in the project.</p>"},{"location":"nav/","title":"Nav","text":""},{"location":"nav/#docforge.nav","title":"docforge.nav","text":"<p>Navigation layer for doc-forge.</p> <p>The <code>docforge.nav</code> package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.</p>"},{"location":"nav/#docforge.nav--workflow","title":"Workflow","text":"<ol> <li>Specification \u2013 Users define navigation intent in <code>docforge.nav.yml</code>.</li> <li>Resolution \u2013 <code>resolve_nav</code> expands patterns and matches them against generated Markdown files.</li> <li>Emission \u2013 <code>MkDocsNavEmitter</code> converts the resolved structure into the YAML navigation format required by <code>mkdocs.yml</code>.</li> </ol> <p>This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.</p>"},{"location":"nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"<p>Emit MkDocs navigation structures from resolved navigation data.</p> <p>The emitter transforms a <code>ResolvedNav</code> object into the YAML-compatible list structure expected by the MkDocs <code>nav</code> configuration field.</p>"},{"location":"nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"<pre><code>emit(nav: ResolvedNav) -> list[dict[str, Any]]\n</code></pre> <p>Generate a navigation structure for <code>mkdocs.yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>nav</code> <code>ResolvedNav</code> <p>Resolved navigation data describing documentation groups and their associated Markdown files.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.</p>"},{"location":"nav/#docforge.nav.NavSpec","title":"NavSpec","text":"<pre><code>NavSpec(\n home: str | None,\n groups: dict[str, list[str]],\n icon: dict[str, str] | None = None,\n)\n</code></pre> <p>Parsed representation of a navigation specification.</p> <p>A <code>NavSpec</code> describes the intended documentation navigation layout before it is resolved against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page (for example <code>index.md</code>).</p> <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of navigation group titles to lists of file patterns or glob expressions.</p> <code>icon</code> <p>Optional mapping of theme icon entries (for example <code>{\"logo\": \"material/code-tags\"}</code>) injected into the MkDocs theme as <code>theme.icon</code>.</p> <p>Initialize a NavSpec instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home document.</p> required <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of group names to lists of path patterns (glob expressions).</p> required <code>icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries applied to the generated MkDocs configuration.</p> <code>None</code>"},{"location":"nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"<pre><code>all_patterns() -> list[str]\n</code></pre> <p>Return all path patterns referenced by the specification.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the home document (if defined) and all group pattern entries.</p>"},{"location":"nav/#docforge.nav.NavSpec.load","title":"load <code>classmethod</code>","text":"<pre><code>load(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Filesystem path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed configuration.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified file does not exist.</p> <code>ValueError</code> <p>If the file contents are not a valid navigation specification.</p>"},{"location":"nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"<pre><code>ResolvedNav(\n home: str | None,\n groups: dict[str, list[Path]],\n docs_root: Path | None = None,\n)\n</code></pre> <p>Resolved navigation structure.</p> <p>A <code>ResolvedNav</code> represents navigation data after glob patterns have been expanded and paths validated against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page.</p> <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of navigation group titles to lists of resolved documentation file paths.</p> <p>Initialize a ResolvedNav instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home page within the documentation root.</p> required <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of group titles to resolved documentation file paths.</p> required <code>docs_root</code> <code>Path | None</code> <p>Root directory of the documentation source files.</p> <code>None</code>"},{"location":"nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"<pre><code>all_files() -> Iterable[Path]\n</code></pre> <p>Iterate over all files referenced by the navigation structure.</p> <p>Yields:</p> Name Type Description <code>Path</code> <code>Iterable[Path]</code> <p>A documentation file referenced by the navigation, including the home page when defined.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the home page is defined but the documentation root is not available for resolution.</p>"},{"location":"nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"<pre><code>build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n</code></pre> <p>Derive an MkDocs navigation block from a wiki directory.</p> <p>Returned paths are relative to the parent of <code>wiki_dir</code> and carry the wiki directory name as their leading component (for example <code>wiki/01_overview.md</code> when the wiki lives at <code>docs/wiki</code>). This makes the result directly usable in an MkDocs <code>nav</code> block with</p> <ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries compatible with the MkDocs <code>nav</code> configuration. The list is empty if the wiki contains no Markdown files.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the wiki directory does not exist.</p>"},{"location":"nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"<pre><code>load_nav_spec(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification file.</p> <p>This helper function reads a YAML navigation file and constructs a corresponding <code>NavSpec</code> instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed specification.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specification file does not exist.</p> <code>ValueError</code> <p>If the YAML structure is invalid.</p>"},{"location":"nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"<pre><code>resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n</code></pre> <p>Resolve a navigation specification against the filesystem.</p> <p>The function expands glob patterns defined in a <code>NavSpec</code> and verifies that referenced documentation files exist within the documentation root.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>NavSpec</code> <p>Navigation specification describing documentation layout.</p> required <code>docs_root</code> <code>Path</code> <p>Root directory containing documentation Markdown files.</p> required <p>Returns:</p> Name Type Description <code>ResolvedNav</code> <code>ResolvedNav</code> <p>A <code>ResolvedNav</code> instance containing validated navigation paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the documentation root does not exist or a navigation pattern does not match any files.</p>"},{"location":"nav/mkdocs/","title":"Mkdocs","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"<p>MkDocs navigation emitter.</p> <p>This module provides the <code>MkDocsNavEmitter</code> class, which converts a <code>ResolvedNav</code> instance into the navigation structure required by the MkDocs <code>nav</code> configuration.</p> Notes <ul> <li>The emitted structure is a list of dictionaries, one per top-level nav entry, matching the MkDocs <code>nav</code> YAML format.</li> </ul>"},{"location":"nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"<p>Emit MkDocs navigation structures from resolved navigation data.</p> <p>The emitter transforms a <code>ResolvedNav</code> object into the YAML-compatible list structure expected by the MkDocs <code>nav</code> configuration field.</p>"},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"<pre><code>emit(nav: ResolvedNav) -> list[dict[str, Any]]\n</code></pre> <p>Generate a navigation structure for <code>mkdocs.yml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>nav</code> <code>ResolvedNav</code> <p>Resolved navigation data describing documentation groups and their associated Markdown files.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.</p>"},{"location":"nav/resolver/","title":"Resolver","text":""},{"location":"nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"<p>Navigation resolution utilities.</p> <p>This module resolves a <code>NavSpec</code> against the filesystem by expanding glob patterns and validating that referenced documentation files exist.</p> Notes <ul> <li>Glob resolution is recursive and returns paths in sorted order.</li> <li>Unmatched patterns raise <code>FileNotFoundError</code> to fail fast on typos.</li> </ul>"},{"location":"nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"<pre><code>ResolvedNav(\n home: str | None,\n groups: dict[str, list[Path]],\n docs_root: Path | None = None,\n)\n</code></pre> <p>Resolved navigation structure.</p> <p>A <code>ResolvedNav</code> represents navigation data after glob patterns have been expanded and paths validated against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page.</p> <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of navigation group titles to lists of resolved documentation file paths.</p> <p>Initialize a ResolvedNav instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home page within the documentation root.</p> required <code>groups</code> <code>dict[str, list[Path]]</code> <p>Mapping of group titles to resolved documentation file paths.</p> required <code>docs_root</code> <code>Path | None</code> <p>Root directory of the documentation source files.</p> <code>None</code>"},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"<pre><code>all_files() -> Iterable[Path]\n</code></pre> <p>Iterate over all files referenced by the navigation structure.</p> <p>Yields:</p> Name Type Description <code>Path</code> <code>Iterable[Path]</code> <p>A documentation file referenced by the navigation, including the home page when defined.</p> <p>Raises:</p> Type Description <code>RuntimeError</code> <p>If the home page is defined but the documentation root is not available for resolution.</p>"},{"location":"nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"<pre><code>resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n</code></pre> <p>Resolve a navigation specification against the filesystem.</p> <p>The function expands glob patterns defined in a <code>NavSpec</code> and verifies that referenced documentation files exist within the documentation root.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>NavSpec</code> <p>Navigation specification describing documentation layout.</p> required <code>docs_root</code> <code>Path</code> <p>Root directory containing documentation Markdown files.</p> required <p>Returns:</p> Name Type Description <code>ResolvedNav</code> <code>ResolvedNav</code> <p>A <code>ResolvedNav</code> instance containing validated navigation paths.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the documentation root does not exist or a navigation pattern does not match any files.</p>"},{"location":"nav/spec/","title":"Spec","text":""},{"location":"nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"<p>Navigation specification model.</p> <p>This module defines the <code>NavSpec</code> class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically <code>docforge.nav.yml</code>).</p> Notes <ul> <li>The spec file supports an optional <code>icon</code> mapping for MkDocs theme customization.</li> <li>All file references in <code>groups</code> are relative to the documentation root.</li> </ul>"},{"location":"nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"<pre><code>NavSpec(\n home: str | None,\n groups: dict[str, list[str]],\n icon: dict[str, str] | None = None,\n)\n</code></pre> <p>Parsed representation of a navigation specification.</p> <p>A <code>NavSpec</code> describes the intended documentation navigation layout before it is resolved against the filesystem.</p> <p>Attributes:</p> Name Type Description <code>home</code> <code>str | None</code> <p>Relative path to the documentation home page (for example <code>index.md</code>).</p> <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of navigation group titles to lists of file patterns or glob expressions.</p> <code>icon</code> <p>Optional mapping of theme icon entries (for example <code>{\"logo\": \"material/code-tags\"}</code>) injected into the MkDocs theme as <code>theme.icon</code>.</p> <p>Initialize a NavSpec instance.</p> <p>Parameters:</p> Name Type Description Default <code>home</code> <code>str | None</code> <p>Relative path to the home document.</p> required <code>groups</code> <code>dict[str, list[str]]</code> <p>Mapping of group names to lists of path patterns (glob expressions).</p> required <code>icon</code> <code>dict[str, str] | None</code> <p>Optional mapping of theme icon entries applied to the generated MkDocs configuration.</p> <code>None</code>"},{"location":"nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"<pre><code>all_patterns() -> list[str]\n</code></pre> <p>Return all path patterns referenced by the specification.</p> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: A list containing the home document (if defined) and all group pattern entries.</p>"},{"location":"nav/spec/#docforge.nav.spec.NavSpec.load","title":"load <code>classmethod</code>","text":"<pre><code>load(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification from a YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Filesystem path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed configuration.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specified file does not exist.</p> <code>ValueError</code> <p>If the file contents are not a valid navigation specification.</p>"},{"location":"nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"<pre><code>load_nav_spec(path: Path) -> NavSpec\n</code></pre> <p>Load a navigation specification file.</p> <p>This helper function reads a YAML navigation file and constructs a corresponding <code>NavSpec</code> instance.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>Path to the navigation specification file.</p> required <p>Returns:</p> Name Type Description <code>NavSpec</code> <code>NavSpec</code> <p>A <code>NavSpec</code> instance representing the parsed specification.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the specification file does not exist.</p> <code>ValueError</code> <p>If the YAML structure is invalid.</p>"},{"location":"nav/wiki/","title":"Wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"<p>Wiki navigation derivation.</p> <p>This module provides <code>build_wiki_nav</code>, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically <code>docs/wiki</code>). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.</p>"},{"location":"nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":"<ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul>"},{"location":"nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"<pre><code>build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n</code></pre> <p>Derive an MkDocs navigation block from a wiki directory.</p> <p>Returned paths are relative to the parent of <code>wiki_dir</code> and carry the wiki directory name as their leading component (for example <code>wiki/01_overview.md</code> when the wiki lives at <code>docs/wiki</code>). This makes the result directly usable in an MkDocs <code>nav</code> block with</p> <ul> <li><code>index.md</code> at the wiki root becomes the <code>Home</code> entry.</li> <li>Page labels are derived from filenames: numeric order prefixes such as <code>01_</code> or <code>02-</code> are stripped, separators are replaced with spaces, and names are title-cased (<code>01_overview.md</code> becomes <code>Overview</code>).</li> <li>Subdirectories become nested navigation groups. A nested <code>index.md</code> is rendered as the section root placed first inside the group.</li> <li>Only <code>.md</code> files are considered; hidden entries are ignored.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>wiki_dir</code> <code>Path</code> <p>Path to the hand-written wiki directory, for example <code>docs/wiki</code>.</p> required <p>Returns:</p> Type Description <code>list[dict[str, Any]]</code> <p>list[dict[str, Any]]: Navigation entries compatible with the MkDocs <code>nav</code> configuration. The list is empty if the wiki contains no Markdown files.</p> <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the wiki directory does not exist.</p>"},{"location":"renderers/","title":"Renderers","text":""},{"location":"renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"renderers/#docforge.renderers--summary","title":"Summary","text":"<p>Renderers layer for doc-forge.</p> <p>The <code>docforge.renderers</code> package transforms the internal documentation models into files formatted for specific documentation systems.</p>"},{"location":"renderers/#docforge.renderers--overview","title":"Overview","text":"<p>Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.</p> <p>Current implementations:</p> <ul> <li>MkDocsRenderer \u2013 Produces Markdown files compatible with MkDocs and the <code>mkdocstrings</code> plugin. It automatically handles package hierarchy and generates <code>index.md</code> files for packages.</li> <li>MCPRenderer \u2013 Emits structured JSON resources designed for consumption by Model Context Protocol (MCP) clients.</li> </ul>"},{"location":"renderers/#docforge.renderers--extending","title":"Extending","text":"<p>New renderers can be added by implementing the <code>DocRenderer</code> protocol defined in <code>docforge.renderers.base</code>.</p>"},{"location":"renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"renderers/base/","title":"Base","text":""},{"location":"renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"<p>Renderer base interfaces and configuration models.</p> <p>This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the <code>DocRenderer</code> protocol.</p>"},{"location":"renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"<p> Bases: <code>Protocol</code></p> <p>Protocol defining the interface for documentation renderers.</p> <p>Implementations of this protocol are responsible for transforming a <code>Project</code> model into renderer-specific documentation sources.</p>"},{"location":"renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate renderer-specific documentation sources.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules and documentation objects.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated documentation sources should be written.</p> required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"<pre><code>RendererConfig(out_dir: Path, project: Project)\n</code></pre> <p>Configuration container for documentation renderers.</p> <p>A <code>RendererConfig</code> instance groups together the project model and the output directory used during rendering.</p> <p>Attributes:</p> Name Type Description <code>out_dir</code> <code>Path</code> <p>Directory where generated documentation files will be written.</p> <code>project</code> <code>Project</code> <p>Documentation project model to be rendered.</p> <p>Initialize a RendererConfig instance.</p> <p>Parameters:</p> Name Type Description Default <code>out_dir</code> <code>Path</code> <p>Target directory where documentation files should be written.</p> required <code>project</code> <code>Project</code> <p>Introspected project model to render.</p> required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"<p>MCP renderer implementation.</p> <p>This module defines the <code>MCPRenderer</code> class, which generates documentation resources compatible with the Model Context Protocol (MCP).</p>"},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"<p>Renderer that generates MCP-compatible documentation resources.</p> <p>This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).</p>"},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(project: Project, out_dir: Path) -> None\n</code></pre> <p>Generate MCP documentation resources for a project.</p> <p>The renderer serializes each module into a JSON resource and produces supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Documentation project model to render.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where MCP resources will be written.</p> required"},{"location":"renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"<p>MkDocs renderer implementation.</p> <p>This module defines the <code>MkDocsRenderer</code> class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.</p> <p>The renderer ensures a consistent documentation structure by:</p> <ul> <li>Creating a root <code>index.md</code> if one does not exist</li> <li>Generating package index pages automatically</li> <li>Linking child modules within parent package pages</li> <li>Optionally generating <code>README.md</code> from the root package docstring</li> </ul>"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"<p>Renderer that produces Markdown documentation for MkDocs.</p> <p>Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.</p>"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"<pre><code>generate_readme(\n project: Project,\n docs_dir: Path,\n module_is_source: bool | None = None,\n readme_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate a <code>README.md</code> file from the root module docstring.</p> Notes <ul> <li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the project root directory.</li> <li>If False, README generation is currently not implemented.</li> </ul> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing documentation metadata.</p> required <code>docs_dir</code> <code>Path</code> <p>Directory containing generated documentation sources.</p> required <code>module_is_source</code> <code>bool | None</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Path | None</code> <p>Directory where the generated README.md should be written. Defaults to the parent of <code>docs_dir</code>.</p> <code>None</code>"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"<pre><code>generate_sources(\n project: Project,\n out_dir: Path,\n module_is_source: bool | None = None,\n) -> None\n</code></pre> <p>Generate Markdown documentation files for a project.</p> <p>This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>Project model containing modules to document.</p> required <code>out_dir</code> <code>Path</code> <p>Directory where generated Markdown files will be written.</p> required <code>module_is_source</code> <code>bool | None</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"servers/","title":"Servers","text":""},{"location":"servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"servers/#docforge.servers--summary","title":"Summary","text":"<p>Server layer for doc-forge.</p> <p>This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.</p>"},{"location":"servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"servers/#docforge.servers.MCPServer","title":"MCPServer","text":"<pre><code>MCPServer(mcp_root: Path, name: str)\n</code></pre> <p>MCP server for serving a pre-generated documentation bundle.</p> <p>The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.</p> <p>Attributes:</p> Name Type Description <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle.</p> <code>app</code> <code>FastMCP</code> <p>Underlying FastMCP application instance that registers resources and tools.</p> <p>Initialize the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle (for example <code>index.json</code>, <code>nav.json</code>, and <code>modules/</code>).</p> required <code>name</code> <code>str</code> <p>Identifier used for the MCP server instance.</p> required"},{"location":"servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"servers/#docforge.servers.MCPServer.run","title":"run","text":"<pre><code>run(\n transport: Literal[\n \"stdio\", \"sse\", \"streamable-http\"\n ] = \"streamable-http\",\n) -> None\n</code></pre> <p>Start the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>transport</code> <code>Literal['stdio', 'sse', 'streamable-http']</code> <p>Transport mechanism used by the MCP server. Supported options include <code>stdio</code>, <code>sse</code>, and <code>streamable-http</code>.</p> <code>'streamable-http'</code>"},{"location":"servers/mcp_server/","title":"Mcp Server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"<p>MCP server implementation.</p> <p>This module defines the <code>MCPServer</code> class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).</p> Notes <ul> <li>The served bundle is generated offline by <code>MCPRenderer</code>.</li> <li>Missing resources are reported as structured error dictionaries rather than raising exceptions.</li> <li>The server exposes read-only resources and a single health-check tool.</li> </ul>"},{"location":"servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"<pre><code>MCPServer(mcp_root: Path, name: str)\n</code></pre> <p>MCP server for serving a pre-generated documentation bundle.</p> <p>The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.</p> <p>Attributes:</p> Name Type Description <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle.</p> <code>app</code> <code>FastMCP</code> <p>Underlying FastMCP application instance that registers resources and tools.</p> <p>Initialize the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>mcp_root</code> <code>Path</code> <p>Directory containing the generated MCP documentation bundle (for example <code>index.json</code>, <code>nav.json</code>, and <code>modules/</code>).</p> required <code>name</code> <code>str</code> <p>Identifier used for the MCP server instance.</p> required"},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"<pre><code>run(\n transport: Literal[\n \"stdio\", \"sse\", \"streamable-http\"\n ] = \"streamable-http\",\n) -> None\n</code></pre> <p>Start the MCP server.</p> <p>Parameters:</p> Name Type Description Default <code>transport</code> <code>Literal['stdio', 'sse', 'streamable-http']</code> <p>Transport mechanism used by the MCP server. Supported options include <code>stdio</code>, <code>sse</code>, and <code>streamable-http</code>.</p> <code>'streamable-http'</code>"}]} |