Vishesh 'ironeagle' Bangotra
42e5ed290e
- compute per-kind home URLs (lib/, api/, wiki/) via _find_home_for_kind - emit one card per declared kind so multi-kind repos (e.g. doc-forge with lib + wiki) appear in each matching homepage section - declare the doc-forge wiki kind and refresh its vendored site with the combined lib + wiki build
1 line
218 KiB
JSON
1 line
218 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"lib/","title":"docforge","text":"<ul> <li>Docforge</li> </ul>"},{"location":"lib/#docforge","title":"docforge","text":""},{"location":"lib/#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":"lib/#docforge--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install doc-forge\n</code></pre>"},{"location":"lib/#docforge--cli-usage","title":"CLI usage","text":""},{"location":"lib/#docforge--generate-an-mkdocs-site-from-a-python-package","title":"Generate an MkDocs site from a Python package:","text":"<pre><code>doc-forge build --mkdocs --module my_package\n</code></pre>"},{"location":"lib/#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"<pre><code>doc-forge build --mcp --module my_package\n</code></pre>"},{"location":"lib/#docforge--generate-mkdocs-site-and-mcp-json-documentation","title":"Generate MkDocs site and MCP JSON documentation:","text":"<pre><code>doc-forge build --mcp --mkdocs --module my_package\n</code></pre>"},{"location":"lib/#docforge--serve-mkdocs-locally","title":"Serve MkDocs locally:","text":"<pre><code>doc-forge serve --mkdocs --module my_package\n</code></pre>"},{"location":"lib/#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"<pre><code>doc-forge serve --mcp --module my_package\n</code></pre>"},{"location":"lib/#docforge--core-concepts","title":"Core concepts","text":""},{"location":"lib/#docforge--loader","title":"Loader","text":"<p>Extracts symbols, signatures, and docstrings using static analysis.</p>"},{"location":"lib/#docforge--semantic-model","title":"Semantic model","text":"<p>Structured, renderer-agnostic representation of the API.</p>"},{"location":"lib/#docforge--renderer","title":"Renderer","text":"<p>Converts the semantic model into output formats such as MkDocs or MCP JSON.</p>"},{"location":"lib/#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":"lib/#docforge--architecture","title":"Architecture","text":"<p><code>doc-forge</code> follows a compiler architecture:</p>"},{"location":"lib/#docforge--front-end","title":"Front-end:","text":"<p>Static analysis of modules, classes, functions, type hints, and docstrings.</p>"},{"location":"lib/#docforge--middle-end","title":"Middle-end:","text":"<p>Builds a semantic model describing symbols and relationships.</p>"},{"location":"lib/#docforge--back-end","title":"Back-end:","text":"<p>Renders documentation using interchangeable renderers.</p> <p>This architecture ensures deterministic documentation generation.</p>"},{"location":"lib/#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":"lib/#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":"lib/#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 instead of duplicating types in prose.</li> <li>Write summaries in imperative form.</li> <li>Sections are separated by <code>---</code></li> </ul>"},{"location":"lib/#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":"lib/#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 structured sections.</p>"},{"location":"lib/#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":"lib/#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":"lib/#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":"lib/#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":"lib/#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":"lib/#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":"lib/#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":"lib/#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":"lib/#docforge-classes","title":"Classes","text":""},{"location":"lib/#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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/#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>"},{"location":"lib/#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,\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</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</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":"lib/#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":"lib/#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/#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":"lib/#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":"lib/#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/#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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/#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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/#docforge-functions","title":"Functions","text":""},{"location":"lib/#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</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":"lib/cli/","title":"Cli","text":""},{"location":"lib/cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"lib/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":"lib/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":"lib/cli/api_utils/","title":"Api Utils","text":""},{"location":"lib/cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"lib/cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"<p>Utilities for building API documentation from an OpenAPI specification.</p>"},{"location":"lib/cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"lib/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":"lib/cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"lib/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[Any, Any]</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":"lib/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[Any, Any]</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":"lib/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":"lib/cli/commands/","title":"Commands","text":""},{"location":"lib/cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"lib/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>"},{"location":"lib/cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"lib/cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"lib/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 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 mkdocs_yml: Path,\n out_dir: Path,\n) -> None\n</code></pre> <p>Build documentation artifacts.</p> <p>This command performs the full documentation build pipeline: style of the selected platform, 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>MkDocs static documentation sites for library reference docs</li> <li>Swagger-enabled API docs generated from an OpenAPI spec</li> <li>Hand-written wiki pages included in the MkDocs site</li> <li>MCP structured documentation resources</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 MkDocs library 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>Include a hand-written wiki directory in the MkDocs site.</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>Optional[str]</code> <p>Python module import path to document.</p> required <code>openapi_spec</code> <code>Optional[Path]</code> <p>Path to the OpenAPI JSON specification used for API docs.</p> required <code>project_name</code> <code>Optional[str]</code> <p>Optional override for the project name.</p> required <code>site_name</code> <code>Optional[str]</code> <p>Display name for the MkDocs site.</p> required <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used as the MkDocs <code>docs_dir</code>.</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>Optional[Path]</code> <p>Optional custom MkDocs configuration template.</p> required <code>mkdocs_yml</code> <code>Path</code> <p>Output path for the generated MkDocs configuration.</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":"lib/cli/commands/#docforge.cli.commands.serve","title":"serve","text":"<pre><code>serve(\n mcp: bool,\n mkdocs: 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 documentation</li> <li>An MCP server exposing structured documentation resources</li> </ul> <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.</p> required <code>module</code> <code>Optional[str]</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":"lib/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>Optional[str]</code> <p>Optional name to display as the project root.</p> required"},{"location":"lib/cli/main/","title":"Main","text":""},{"location":"lib/cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"lib/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":"lib/cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"lib/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":"lib/cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"lib/cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"lib/cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"<p>Utilities for working with MCP in the doc-forge CLI.</p>"},{"location":"lib/cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"lib/cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"lib/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>Optional[str]</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":"lib/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":"lib/cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"<p>Utilities for working with MkDocs in the doc-forge CLI.</p>"},{"location":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build","title":"build","text":"<pre><code>build(mkdocs_yml: Path) -> None\n</code></pre> <p>Build the MkDocs documentation site.</p> <p>This function loads the MkDocs configuration and runs the MkDocs build command to generate the final static documentation site.</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":"lib/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_config","title":"generate_config","text":"<pre><code>generate_config(\n docs_dir: Path,\n nav_file: Path,\n template: Path | None,\n out: Path,\n site_name: str,\n modes: Iterable[str] | None = None,\n site_description: str | None = None,\n site_author: str | None = None,\n wiki_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate an <code>mkdocs.yml</code> configuration file.</p> <p>The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation specification (and, when a wiki directory is provided, from the wiki file structure).</p> <p>The <code>docs_dir</code> is always written relative to the MkDocs root and is expected to be the shared documentation parent (for example <code>docs</code>), with generated sources nested under <code>lib/</code> or <code>api/</code> subdirectories and hand-written wiki content under a <code>wiki/</code> subdirectory.</p> <p>Parameters:</p> Name Type Description Default <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used as the MkDocs <code>docs_dir</code>.</p> required <code>nav_file</code> <code>Path</code> <p>Path to the <code>docforge.nav.yml</code> navigation specification.</p> required <code>template</code> <code>Optional[Path]</code> <p>Optional path to a fully custom MkDocs configuration template. If not provided, built-in templates are merged; the provided template replaces the built-in templates entirely.</p> required <code>out</code> <code>Path</code> <p>Destination path where the generated <code>mkdocs.yml</code> file will be written.</p> required <code>site_name</code> <code>str</code> <p>Display name for the generated documentation site.</p> required <code>modes</code> <code>Optional[Iterable[str]]</code> <p>Documentation modes to enable. Each mode contributes its own built-in template fragment (for example <code>lib</code>, <code>api</code>, or <code>wiki</code>), merged on top of the shared <code>mkdocs.common.yml</code> template.</p> <code>None</code> <code>site_description</code> <code>Optional[str]</code> <p>Optional site description written into the configuration.</p> <code>None</code> <code>site_author</code> <code>Optional[str]</code> <p>Optional site author written into the configuration.</p> <code>None</code> <code>wiki_dir</code> <code>Optional[Path]</code> <p>Optional path to a hand-written wiki directory (for example <code>docs/wiki</code>). When provided, the site navigation is derived from the wiki file structure and placed before the navigation groups defined in <code>nav_file</code>.</p> <code>None</code> <p>Raises:</p> Type Description <code>FileError</code> <p>If the navigation specification, template, or wiki directory cannot be found.</p>"},{"location":"lib/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>Optional[str]</code> <p>Optional override for the project name used in documentation metadata.</p> <code>None</code> <code>module_is_source</code> <code>Optional[bool]</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>Optional[Path]</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":"lib/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":"lib/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":"lib/docforge/#docforge","title":"docforge","text":""},{"location":"lib/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":"lib/docforge/#docforge--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install doc-forge\n</code></pre>"},{"location":"lib/docforge/#docforge--cli-usage","title":"CLI usage","text":""},{"location":"lib/docforge/#docforge--generate-an-mkdocs-site-from-a-python-package","title":"Generate an MkDocs site from a Python package:","text":"<pre><code>doc-forge build --mkdocs --module my_package\n</code></pre>"},{"location":"lib/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":"lib/docforge/#docforge--generate-mkdocs-site-and-mcp-json-documentation","title":"Generate MkDocs site and MCP JSON documentation:","text":"<pre><code>doc-forge build --mcp --mkdocs --module my_package\n</code></pre>"},{"location":"lib/docforge/#docforge--serve-mkdocs-locally","title":"Serve MkDocs locally:","text":"<pre><code>doc-forge serve --mkdocs --module my_package\n</code></pre>"},{"location":"lib/docforge/#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"<pre><code>doc-forge serve --mcp --module my_package\n</code></pre>"},{"location":"lib/docforge/#docforge--core-concepts","title":"Core concepts","text":""},{"location":"lib/docforge/#docforge--loader","title":"Loader","text":"<p>Extracts symbols, signatures, and docstrings using static analysis.</p>"},{"location":"lib/docforge/#docforge--semantic-model","title":"Semantic model","text":"<p>Structured, renderer-agnostic representation of the API.</p>"},{"location":"lib/docforge/#docforge--renderer","title":"Renderer","text":"<p>Converts the semantic model into output formats such as MkDocs or MCP JSON.</p>"},{"location":"lib/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":"lib/docforge/#docforge--architecture","title":"Architecture","text":"<p><code>doc-forge</code> follows a compiler architecture:</p>"},{"location":"lib/docforge/#docforge--front-end","title":"Front-end:","text":"<p>Static analysis of modules, classes, functions, type hints, and docstrings.</p>"},{"location":"lib/docforge/#docforge--middle-end","title":"Middle-end:","text":"<p>Builds a semantic model describing symbols and relationships.</p>"},{"location":"lib/docforge/#docforge--back-end","title":"Back-end:","text":"<p>Renders documentation using interchangeable renderers.</p> <p>This architecture ensures deterministic documentation generation.</p>"},{"location":"lib/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":"lib/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":"lib/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 instead of duplicating types in prose.</li> <li>Write summaries in imperative form.</li> <li>Sections are separated by <code>---</code></li> </ul>"},{"location":"lib/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":"lib/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 structured sections.</p>"},{"location":"lib/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":"lib/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":"lib/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":"lib/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":"lib/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":"lib/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":"lib/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":"lib/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":"lib/docforge/#docforge-classes","title":"Classes","text":""},{"location":"lib/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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/docforge/#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/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>"},{"location":"lib/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,\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</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</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":"lib/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":"lib/docforge/#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/docforge/#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/docforge/#docforge-functions","title":"Functions","text":""},{"location":"lib/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</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":"lib/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":"lib/docforge/cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"lib/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":"lib/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":"lib/docforge/cli/api_utils/","title":"Api Utils","text":""},{"location":"lib/docforge/cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"lib/docforge/cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"<p>Utilities for building API documentation from an OpenAPI specification.</p>"},{"location":"lib/docforge/cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"lib/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[Any, Any]</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":"lib/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[Any, Any]</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":"lib/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":"lib/docforge/cli/commands/","title":"Commands","text":""},{"location":"lib/docforge/cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"lib/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>"},{"location":"lib/docforge/cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"lib/docforge/cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"lib/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 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 mkdocs_yml: Path,\n out_dir: Path,\n) -> None\n</code></pre> <p>Build documentation artifacts.</p> <p>This command performs the full documentation build pipeline: style of the selected platform, 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>MkDocs static documentation sites for library reference docs</li> <li>Swagger-enabled API docs generated from an OpenAPI spec</li> <li>Hand-written wiki pages included in the MkDocs site</li> <li>MCP structured documentation resources</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 MkDocs library 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>Include a hand-written wiki directory in the MkDocs site.</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>Optional[str]</code> <p>Python module import path to document.</p> required <code>openapi_spec</code> <code>Optional[Path]</code> <p>Path to the OpenAPI JSON specification used for API docs.</p> required <code>project_name</code> <code>Optional[str]</code> <p>Optional override for the project name.</p> required <code>site_name</code> <code>Optional[str]</code> <p>Display name for the MkDocs site.</p> required <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used as the MkDocs <code>docs_dir</code>.</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>Optional[Path]</code> <p>Optional custom MkDocs configuration template.</p> required <code>mkdocs_yml</code> <code>Path</code> <p>Output path for the generated MkDocs configuration.</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":"lib/docforge/cli/commands/#docforge.cli.commands.serve","title":"serve","text":"<pre><code>serve(\n mcp: bool,\n mkdocs: 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 documentation</li> <li>An MCP server exposing structured documentation resources</li> </ul> <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.</p> required <code>module</code> <code>Optional[str]</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":"lib/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>Optional[str]</code> <p>Optional name to display as the project root.</p> required"},{"location":"lib/docforge/cli/main/","title":"Main","text":""},{"location":"lib/docforge/cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"lib/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":"lib/docforge/cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"lib/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":"lib/docforge/cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"lib/docforge/cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"lib/docforge/cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"<p>Utilities for working with MCP in the doc-forge CLI.</p>"},{"location":"lib/docforge/cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"lib/docforge/cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"lib/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>Optional[str]</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":"lib/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":"lib/docforge/cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"<p>Utilities for working with MkDocs in the doc-forge CLI.</p>"},{"location":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build","title":"build","text":"<pre><code>build(mkdocs_yml: Path) -> None\n</code></pre> <p>Build the MkDocs documentation site.</p> <p>This function loads the MkDocs configuration and runs the MkDocs build command to generate the final static documentation site.</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":"lib/docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_config","title":"generate_config","text":"<pre><code>generate_config(\n docs_dir: Path,\n nav_file: Path,\n template: Path | None,\n out: Path,\n site_name: str,\n modes: Iterable[str] | None = None,\n site_description: str | None = None,\n site_author: str | None = None,\n wiki_dir: Path | None = None,\n) -> None\n</code></pre> <p>Generate an <code>mkdocs.yml</code> configuration file.</p> <p>The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation specification (and, when a wiki directory is provided, from the wiki file structure).</p> <p>The <code>docs_dir</code> is always written relative to the MkDocs root and is expected to be the shared documentation parent (for example <code>docs</code>), with generated sources nested under <code>lib/</code> or <code>api/</code> subdirectories and hand-written wiki content under a <code>wiki/</code> subdirectory.</p> <p>Parameters:</p> Name Type Description Default <code>docs_dir</code> <code>Path</code> <p>Shared documentation root used as the MkDocs <code>docs_dir</code>.</p> required <code>nav_file</code> <code>Path</code> <p>Path to the <code>docforge.nav.yml</code> navigation specification.</p> required <code>template</code> <code>Optional[Path]</code> <p>Optional path to a fully custom MkDocs configuration template. If not provided, built-in templates are merged; the provided template replaces the built-in templates entirely.</p> required <code>out</code> <code>Path</code> <p>Destination path where the generated <code>mkdocs.yml</code> file will be written.</p> required <code>site_name</code> <code>str</code> <p>Display name for the generated documentation site.</p> required <code>modes</code> <code>Optional[Iterable[str]]</code> <p>Documentation modes to enable. Each mode contributes its own built-in template fragment (for example <code>lib</code>, <code>api</code>, or <code>wiki</code>), merged on top of the shared <code>mkdocs.common.yml</code> template.</p> <code>None</code> <code>site_description</code> <code>Optional[str]</code> <p>Optional site description written into the configuration.</p> <code>None</code> <code>site_author</code> <code>Optional[str]</code> <p>Optional site author written into the configuration.</p> <code>None</code> <code>wiki_dir</code> <code>Optional[Path]</code> <p>Optional path to a hand-written wiki directory (for example <code>docs/wiki</code>). When provided, the site navigation is derived from the wiki file structure and placed before the navigation groups defined in <code>nav_file</code>.</p> <code>None</code> <p>Raises:</p> Type Description <code>FileError</code> <p>If the navigation specification, template, or wiki directory cannot be found.</p>"},{"location":"lib/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>Optional[str]</code> <p>Optional override for the project name used in documentation metadata.</p> <code>None</code> <code>module_is_source</code> <code>Optional[bool]</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>Optional[Path]</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":"lib/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":"lib/docforge/loaders/","title":"Loaders","text":"<ul> <li>Griffe Loader</li> </ul>"},{"location":"lib/docforge/loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"lib/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":"lib/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":"lib/docforge/loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"lib/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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/docforge/loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/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>"},{"location":"lib/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,\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</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</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":"lib/docforge/loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"lib/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</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":"lib/docforge/loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"lib/docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"lib/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>"},{"location":"lib/docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"lib/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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/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>"},{"location":"lib/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,\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</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</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":"lib/docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"lib/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</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":"lib/docforge/models/","title":"Models","text":"<ul> <li>Module</li> <li>Object</li> <li>Project</li> </ul>"},{"location":"lib/docforge/models/#docforge.models","title":"docforge.models","text":""},{"location":"lib/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":"lib/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":"lib/docforge/models/#docforge.models-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>Optional[str]</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>Optional[str]</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>Optional[str]</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"lib/docforge/models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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>Optional[str]</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>Optional[str]</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"lib/docforge/models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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"},{"location":"lib/docforge/models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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":"lib/docforge/models/module/","title":"Module","text":""},{"location":"lib/docforge/models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"lib/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>"},{"location":"lib/docforge/models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</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>Optional[str]</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"lib/docforge/models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/docforge/models/object/","title":"Object","text":""},{"location":"lib/docforge/models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"lib/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>"},{"location":"lib/docforge/models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>Optional[str]</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>Optional[str]</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>Optional[str]</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"lib/docforge/models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/docforge/models/project/","title":"Project","text":""},{"location":"lib/docforge/models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"lib/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>"},{"location":"lib/docforge/models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"lib/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"},{"location":"lib/docforge/models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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":"lib/docforge/nav/","title":"Nav","text":"<ul> <li>Mkdocs</li> <li>Resolver</li> <li>Spec</li> <li>Wiki</li> </ul>"},{"location":"lib/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":"lib/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":"lib/docforge/nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"lib/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>A list of dictionaries representing the MkDocs navigation layout.</p> <code>list[dict[str, Any]]</code> <p>Each dictionary maps a navigation label to a page or a list of</p> <code>list[dict[str, Any]]</code> <p>pages.</p>"},{"location":"lib/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":"lib/docforge/nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"lib/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>A list containing the home document (if defined) and all</p> <code>list[str]</code> <p>group pattern entries.</p>"},{"location":"lib/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> Type Description <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":"lib/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":"lib/docforge/nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"lib/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>Returns:</p> Type Description <code>Iterable[Path]</code> <p>An iterable of <code>Path</code> objects representing documentation files.</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":"lib/docforge/nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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> Type Description <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":"lib/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> Type Description <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":"lib/docforge/nav/mkdocs/","title":"Mkdocs","text":""},{"location":"lib/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>"},{"location":"lib/docforge/nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"lib/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>A list of dictionaries representing the MkDocs navigation layout.</p> <code>list[dict[str, Any]]</code> <p>Each dictionary maps a navigation label to a page or a list of</p> <code>list[dict[str, Any]]</code> <p>pages.</p>"},{"location":"lib/docforge/nav/resolver/","title":"Resolver","text":""},{"location":"lib/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>"},{"location":"lib/docforge/nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"lib/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>Returns:</p> Type Description <code>Iterable[Path]</code> <p>An iterable of <code>Path</code> objects representing documentation files.</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":"lib/docforge/nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"lib/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> Type Description <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":"lib/docforge/nav/spec/","title":"Spec","text":""},{"location":"lib/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>"},{"location":"lib/docforge/nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"lib/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>A list containing the home document (if defined) and all</p> <code>list[str]</code> <p>group pattern entries.</p>"},{"location":"lib/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> Type Description <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":"lib/docforge/nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"lib/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> Type Description <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":"lib/docforge/nav/wiki/","title":"Wiki","text":""},{"location":"lib/docforge/nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"lib/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":"lib/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":"lib/docforge/nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"lib/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":"lib/docforge/renderers/","title":"Renderers","text":"<ul> <li>Base</li> <li>Mcp Renderer</li> <li>Mkdocs Renderer</li> </ul>"},{"location":"lib/docforge/renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/docforge/renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/docforge/renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/docforge/renderers/base/","title":"Base","text":""},{"location":"lib/docforge/renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"lib/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":"lib/docforge/renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/docforge/renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"lib/docforge/renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"lib/docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"lib/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":"lib/docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/docforge/renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"lib/docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"lib/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":"lib/docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"lib/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":"lib/docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/docforge/servers/","title":"Servers","text":"<ul> <li>Mcp Server</li> </ul>"},{"location":"lib/docforge/servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"lib/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":"lib/docforge/servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"lib/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>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":"lib/docforge/servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/docforge/servers/mcp_server/","title":"Mcp Server","text":""},{"location":"lib/docforge/servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"lib/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>"},{"location":"lib/docforge/servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"lib/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>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":"lib/docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/loaders/","title":"Loaders","text":""},{"location":"lib/loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"lib/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":"lib/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":"lib/loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"lib/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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/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>"},{"location":"lib/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,\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</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</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":"lib/loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"lib/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</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":"lib/loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"lib/loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"lib/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>"},{"location":"lib/loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"lib/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>Initialize the Griffe-backed loader.</p> <p>Creates an internal Griffe loader instance with dedicated collections for modules and source lines.</p>"},{"location":"lib/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"lib/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>"},{"location":"lib/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,\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</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</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":"lib/loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"lib/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</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":"lib/models/","title":"Models","text":""},{"location":"lib/models/#docforge.models","title":"docforge.models","text":""},{"location":"lib/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":"lib/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":"lib/models/#docforge.models-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>Optional[str]</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>Optional[str]</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>Optional[str]</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"lib/models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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>Optional[str]</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>Optional[str]</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"lib/models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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"},{"location":"lib/models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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":"lib/models/module/","title":"Module","text":""},{"location":"lib/models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"lib/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>"},{"location":"lib/models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</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>Optional[str]</code> <p>Module-level documentation text, if available.</p> <code>None</code>"},{"location":"lib/models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/models/object/","title":"Object","text":""},{"location":"lib/models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"lib/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>"},{"location":"lib/models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"lib/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>Optional[str]</code> <p>Callable signature if the object represents a callable.</p> <code>docstring</code> <code>Optional[str]</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>Optional[str]</code> <p>Callable signature if applicable.</p> <code>None</code> <code>docstring</code> <code>Optional[str]</code> <p>Documentation string associated with the object.</p> <code>None</code>"},{"location":"lib/models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/models/project/","title":"Project","text":""},{"location":"lib/models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"lib/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>"},{"location":"lib/models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"lib/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"},{"location":"lib/models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/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":"lib/nav/","title":"Nav","text":""},{"location":"lib/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":"lib/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":"lib/nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"lib/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":"lib/nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"lib/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>A list of dictionaries representing the MkDocs navigation layout.</p> <code>list[dict[str, Any]]</code> <p>Each dictionary maps a navigation label to a page or a list of</p> <code>list[dict[str, Any]]</code> <p>pages.</p>"},{"location":"lib/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":"lib/nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"lib/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>A list containing the home document (if defined) and all</p> <code>list[str]</code> <p>group pattern entries.</p>"},{"location":"lib/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> Type Description <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":"lib/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":"lib/nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"lib/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>Returns:</p> Type Description <code>Iterable[Path]</code> <p>An iterable of <code>Path</code> objects representing documentation files.</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":"lib/nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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> Type Description <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":"lib/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> Type Description <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":"lib/nav/mkdocs/","title":"Mkdocs","text":""},{"location":"lib/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>"},{"location":"lib/nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"lib/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":"lib/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"lib/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>A list of dictionaries representing the MkDocs navigation layout.</p> <code>list[dict[str, Any]]</code> <p>Each dictionary maps a navigation label to a page or a list of</p> <code>list[dict[str, Any]]</code> <p>pages.</p>"},{"location":"lib/nav/resolver/","title":"Resolver","text":""},{"location":"lib/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>"},{"location":"lib/nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"lib/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":"lib/nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"lib/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>Returns:</p> Type Description <code>Iterable[Path]</code> <p>An iterable of <code>Path</code> objects representing documentation files.</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":"lib/nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"lib/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> Type Description <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":"lib/nav/spec/","title":"Spec","text":""},{"location":"lib/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>"},{"location":"lib/nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"lib/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":"lib/nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"lib/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>A list containing the home document (if defined) and all</p> <code>list[str]</code> <p>group pattern entries.</p>"},{"location":"lib/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> Type Description <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":"lib/nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"lib/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> Type Description <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":"lib/renderers/","title":"Renderers","text":""},{"location":"lib/renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"lib/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":"lib/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":"lib/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":"lib/renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"lib/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":"lib/renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/renderers/base/","title":"Base","text":""},{"location":"lib/renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"lib/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":"lib/renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"lib/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":"lib/renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/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":"lib/renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"lib/renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"lib/renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"lib/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":"lib/renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"lib/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":"lib/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"lib/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"lib/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":"lib/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"lib/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":"lib/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"lib/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> <p>Behavior:</p> <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>Optional[bool]</code> <p>Whether the module is treated as the project source root.</p> <code>None</code> <code>readme_dir</code> <code>Optional[Path]</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":"lib/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</code> <p>If True, treat the specified module as the documentation root rather than nesting it inside a folder.</p> <code>None</code>"},{"location":"lib/servers/","title":"Servers","text":""},{"location":"lib/servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"lib/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":"lib/servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"lib/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>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":"lib/servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"lib/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":"lib/servers/mcp_server/","title":"Mcp Server","text":""},{"location":"lib/servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"lib/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>"},{"location":"lib/servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"lib/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>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":"lib/servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"lib/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":"wiki/","title":"\ud83d\udd28 docforge \u2014 Docstring-Driven Documentation Forge","text":"<p><code>docforge</code> is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into a single MkDocs site, alongside hand-written wiki pages and OpenAPI-based API docs.</p>"},{"location":"wiki/#key-features","title":"\ud83d\ude80 Key Features","text":"<ul> <li>\ud83e\uddea GSDFC docstring extraction via Griffe</li> <li>\ud83e\udded Auto-derived navigation for hand-written wiki pages</li> <li>\ud83d\uddc2 Combined MkDocs build: wiki first, then generated library/API reference</li> <li>\ud83d\udd0c Material MkDocs theming out of the box</li> <li>\ud83d\udce6 MCP structured documentation resources</li> </ul>"},{"location":"wiki/#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Architecture Loaders, models, nav, renderers, CLI Conventions GSDFC, <code>.pyi</code> stubs, and template conventions Iterative Workflow How a docs build runs end to end Development Environment setup and quality gates"},{"location":"wiki/#related-resources","title":"\ud83d\udd17 Related Resources","text":"<ul> <li>Source Code: <code>C:\\Users\\vishe\\WorkSpace\\code\\aetos\\doc-forge</code></li> <li>Wiki Kind: hand-written content lives in <code>docs/wiki/</code></li> </ul> <p>\u00a9 Aetoskia Internal</p>"},{"location":"wiki/01_overview/","title":"Overview","text":"<p><code>docforge</code> turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles a single MkDocs site from all available material.</p>"},{"location":"wiki/01_overview/#what-it-generates","title":"What it generates","text":"Kind Source Output <code>lib</code> GSDFC docstrings <code>docs/lib/**</code> rendered markdown <code>api</code> OpenAPI JSON spec <code>docs/api/**</code> rendered markdown <code>wiki</code> Hand-written markdown <code>docs/wiki/**</code> (unchanged) <code>mcp</code> Griffe + renderers <code>docs/mcp/**</code> structured files"},{"location":"wiki/01_overview/#combined-build","title":"Combined build","text":"<p>One <code>mkdocs.yml</code> and one MkDocs build serve all kinds:</p> <ol> <li>Wiki navigation is derived from the <code>docs/wiki/</code> file structure.</li> <li>Generated library/API navigation is appended after it.</li> <li>The wiki <code>index.md</code> becomes the site <code>Home</code>.</li> </ol> <p>Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.</p>"},{"location":"wiki/02_architecture/","title":"Architecture","text":"<p><code>docforge</code> is split into four horizontal layers. Everything flows top to bottom through the CLI.</p>"},{"location":"wiki/02_architecture/#loaders-models","title":"Loaders \u2192 Models","text":"<p>The <code>docforge/loaders</code> package wraps <code>griffe</code> to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under <code>docforge/models</code> (<code>Module</code>, <code>Object</code>, <code>Project</code>, <code>Field</code>).</p>"},{"location":"wiki/02_architecture/#navigation","title":"Navigation","text":"<p><code>docforge/nav</code> parses <code>docforge.nav.yml</code> specs (<code>NavSpec</code>, <code>Resolver</code>, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via <code>build_wiki_nav</code>.</p>"},{"location":"wiki/02_architecture/#renderers","title":"Renderers","text":"<p><code>docforge/renderers</code> turn model data into artifacts:</p> <ul> <li><code>MkDocsRenderer</code> \u2192 <code>docs/lib/**</code> reference markdown</li> <li><code>MCPRenderer</code> \u2192 <code>docs/mcp/**</code> structured documentation</li> </ul>"},{"location":"wiki/02_architecture/#cli","title":"CLI","text":"<p><code>docforge/cli</code> wires it all together:</p> <ul> <li><code>commands.py</code> \u2014 the <code>build</code> command and its <code>--mkdocs</code> / <code>--api</code> / <code>--wiki</code> / <code>--mcp</code> modes</li> <li><code>mkdocs_utils.py</code> \u2014 config generation (<code>mkdocs.yml</code>) including merged wiki + lib + api navigation</li> <li><code>api_utils.py</code> \u2014 OpenAPI loading and API docs generation</li> </ul>"},{"location":"wiki/03_conventions/","title":"Conventions","text":""},{"location":"wiki/03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"<p>All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): <code>Args:</code>, <code>Returns:</code>, <code>Raises:</code>, and <code>Attributes:</code> sections with properly typed signatures.</p>"},{"location":"wiki/03_conventions/#pyi-stubs","title":"<code>.pyi</code> stubs","text":"<p>Every module ships a matching <code>.pyi</code> stub kept in sync with the <code>.py</code> implementation. When signatures change, update both files.</p>"},{"location":"wiki/03_conventions/#wiki-pages","title":"Wiki pages","text":"<ul> <li>Hand-written markdown lives in <code>docs/wiki/**</code> and is never generated.</li> <li>File names use a numeric prefix: <code>01_overview.md</code>, <code>02_components.md</code>.</li> <li>Nested directories become nested navigation groups: <code>05_development/01_environment.md</code> \u2192 group Development.</li> <li><code>index.md</code> is the site <code>Home</code> at the root, and a section root inside a directory.</li> <li>Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.</li> </ul>"},{"location":"wiki/03_conventions/#templates","title":"Templates","text":"<p>MkDocs config fragments live in <code>docforge/templates</code>. The <code>mkdocs.wiki.yml</code> fragment carries only the <code>search</code> plugin, since wiki pages contain no mkdocstrings directives.</p>"},{"location":"wiki/04_iterative_workflow/","title":"Iterative Workflow","text":"<p>A docs build runs through the CLI in a single pass.</p>"},{"location":"wiki/04_iterative_workflow/#build-commands","title":"Build commands","text":"<pre><code># Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wik + library combined (single MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n</code></pre>"},{"location":"wiki/04_iterative_workflow/#what-a-combined-build-does","title":"What a combined build does","text":"<ol> <li>Validates the requested modes (<code>--mkdocs</code>, <code>--api</code>, <code>--wiki</code>, <code>--mcp</code>).</li> <li>Generates library sources under <code>docs/lib/**</code> with <code>MkDocsRenderer</code>.</li> <li>Generates API sources under <code>docs/api/**</code> when <code>--api</code> is given.</li> <li>Derives wiki navigation from <code>docs/wiki/**</code>.</li> <li>Writes <code>mkdocs.yml</code> with merged navigation \u2014 wiki first, generated groups appended, and the wiki <code>Home</code> replacing any spec <code>Home</code> entry.</li> <li>Runs <code>mkdocs build</code> once and emits the site.</li> </ol>"},{"location":"wiki/04_iterative_workflow/#explore-the-site","title":"Explore the site","text":"<pre><code>doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --mkdocs-yml mkdocs.yml\n</code></pre>"},{"location":"wiki/05_development/01_environment/","title":"Environment Setup","text":""},{"location":"wiki/05_development/01_environment/#create-the-environment","title":"Create the environment","text":"<pre><code>python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n</code></pre> <p>Requires Python 3.11+.</p>"},{"location":"wiki/05_development/01_environment/#dependencies","title":"Dependencies","text":"<p>Development extras include:</p> <ul> <li><code>pytest</code>, <code>pytest-cov</code> \u2014 test suite and coverage</li> <li><code>ruff</code> \u2014 lint and format checking</li> <li><code>black</code> \u2014 auto-formatting</li> <li><code>mypy</code> \u2014 strict typing checks</li> </ul>"},{"location":"wiki/05_development/02_quality_gates/","title":"Quality Gates","text":"<p>Run all checks before pushing:</p> <pre><code>.venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n</code></pre>"},{"location":"wiki/05_development/02_quality_gates/#test-layout","title":"Test layout","text":"Path Covers <code>tests/nav/</code> Nav spec, resolver, wiki nav <code>tests/cli/</code> Build command flows and modes <code>tests/renderers/</code> MkDocs / MCP rendering <p>CLI tests use the <code>cli_runner</code> fixture with <code>mock_mkdocs_build</code> and <code>mock_mkdocs_load_config</code> so they exercise the full flow without invoking a real MkDocs build.</p>"}]} |