{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"docforge","text":""},{"location":"#docforge","title":"docforge","text":""},{"location":"#docforge--summary","title":"Summary","text":"

Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

doc-forge 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.

"},{"location":"#docforge--installation","title":"Installation","text":"

Install using pip:

pip install doc-forge\n
"},{"location":"#docforge--cli-usage","title":"CLI usage","text":"

Each site kind (lib, api, wiki) is built independently into site/{kind}.

"},{"location":"#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"
doc-forge build --mkdocs --module my_package\n
"},{"location":"#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"
doc-forge build --api --openapi-spec spec.json\n
"},{"location":"#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"
doc-forge build --wiki --site-name my_package\n
"},{"location":"#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"
doc-forge build --mcp --module my_package\n
"},{"location":"#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"
doc-forge build --mcp --mkdocs --wiki --module my_package\n

Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/.

"},{"location":"#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"
doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
"},{"location":"#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"
doc-forge serve --mcp --module my_package\n
"},{"location":"#docforge--core-concepts","title":"Core concepts","text":""},{"location":"#docforge--loader","title":"Loader","text":"

Extracts symbols, signatures, and docstrings using static analysis.

"},{"location":"#docforge--semantic-model","title":"Semantic model","text":"

Structured, renderer-agnostic representation of the API.

"},{"location":"#docforge--renderer","title":"Renderer","text":"

Converts the semantic model into output formats such as MkDocs or MCP JSON.

"},{"location":"#docforge--symbol","title":"Symbol","text":"

Any documentable object

"},{"location":"#docforge--architecture","title":"Architecture","text":"

doc-forge follows a compiler architecture:

"},{"location":"#docforge--front-end","title":"Front-end:","text":"

Static analysis of modules, classes, functions, type hints, and docstrings.

"},{"location":"#docforge--middle-end","title":"Middle-end:","text":"

Builds a semantic model describing symbols and relationships.

"},{"location":"#docforge--back-end","title":"Back-end:","text":"

Renders documentation using interchangeable renderers.

This architecture ensures deterministic documentation generation.

"},{"location":"#docforge--rendering-pipeline","title":"Rendering pipeline","text":"

Typical flow:

Python package\n    |\nLoader (static analysis)\n    |\nSemantic model\n    |\nRenderer\n    |\nMkDocs site or MCP JSON\n
"},{"location":"#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"

GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

"},{"location":"#docforge--general-rules","title":"General rules","text":""},{"location":"#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"

Group related information using labeled subsections.

Example:

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
"},{"location":"#docforge--example-formatting","title":"Example formatting","text":" Example

Single example:

Example:\n\n    ```python\n    foo = Foo(\"example\")\n    process(foo, multiplier=2)\n    ```\n

Multiple examples:

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

Avoid fenced code blocks inside argument descriptions and other prose lines.

Inside Example: sections, fenced python code blocks are allowed and must be indented four spaces, matching the examples below.

"},{"location":"#docforge--separator-rules","title":"Separator rules","text":"

Use horizontal separators only at docstring root level to separate sections:

---\n

Allowed locations:

Do not use separators inside code sections.

"},{"location":"#docforge--package-docstrings","title":"Package docstrings","text":"

Package docstrings act as the documentation home page.

Recommended sections:

# Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n
Example

Package Doc String:

'''\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
"},{"location":"#docforge--module-docstrings","title":"Module docstrings","text":"

Module docstrings describe a subsystem.

Recommended sections:

# Summary\n# Examples\n# Notes\n
Example

Module Doc String:

'''\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
"},{"location":"#docforge--class-docstrings","title":"Class docstrings","text":"

Class docstrings define object responsibility, lifecycle, and attributes.

Recommended sections:

Attributes:\nNotes:\nExample:\nRaises:\n
Example

Simple Foo:

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

Complex Bar:

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
"},{"location":"#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"

Function docstrings define API contracts.

Recommended sections:

Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
Example

Simple process method:

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

Multiple Examples:

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
"},{"location":"#docforge--property-docstrings","title":"Property docstrings","text":"

Properties must document return values.

Example

Property Doc String:

```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
"},{"location":"#docforge--attribute-documentation","title":"Attribute documentation","text":"

Document attributes in class docstrings using Attributes:.

Example

Attribute Doc String:

```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
"},{"location":"#docforge--parsing-guarantees","title":"Parsing guarantees","text":"

GSDFC ensures doc-forge can deterministically extract:

This enables:

Notes "},{"location":"#docforge-classes","title":"Classes","text":""},{"location":"#docforge.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"#docforge.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"#docforge.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"#docforge.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"#docforge-functions","title":"Functions","text":""},{"location":"#docforge.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"cli/#docforge.cli--summary","title":"Summary","text":"

Command line interface entry point for doc-forge.

This module exposes the primary CLI entry function used by the doc-forge command. The actual command implementation resides in docforge.cli.main, while this module provides a stable import path for external tools and the package entry point configuration.

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.

"},{"location":"cli/#docforge.cli--typical-usage","title":"Typical usage","text":"

The CLI is normally invoked through the installed command:

doc-forge <command> [options]\n

Programmatic invocation is also possible:

Example:

```python\nfrom docforge.cli import main\nmain()\n```\n
"},{"location":"cli/api_utils/","title":"Api Utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"

Utilities for building API documentation from an OpenAPI specification.

"},{"location":"cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata dataclass","text":"
OpenAPIMetadata(\n    site_name: str,\n    site_description: str | None,\n    site_author: str | None,\n)\n

Metadata derived from the info block of an OpenAPI specification.

Attributes:

Name Type Description site_name str

Spec title, used as the MkDocs site name.

site_description str | None

Spec description, used as the site description.

site_author str | None

Contact name (fallback: contact email), used as the site author.

"},{"location":"cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"
derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n

Derive MkDocs site metadata from an OpenAPI spec info block.

Parameters:

Name Type Description Default spec dict

Parsed OpenAPI specification.

required

Returns:

Name Type Description OpenAPIMetadata OpenAPIMetadata

Site name, description, and author derived from the spec.

"},{"location":"cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"
generate_api_sources(\n    spec: dict[Any, Any], docs_dir: Path\n) -> None\n

Generate swagger-enabled Markdown sources and the spec copy.

The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

Parameters:

Name Type Description Default spec dict

Parsed OpenAPI specification.

required docs_dir Path

Directory (for example docs/api) where the swagger sources are written.

required"},{"location":"cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"
load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n

Load and validate an OpenAPI specification from a JSON file.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI JSON specification file.

required

Returns:

Name Type Description dict dict[Any, Any]

The parsed OpenAPI specification.

Raises:

Type Description ClickException

If the file cannot be read or the info block is invalid.

"},{"location":"cli/commands/","title":"Commands","text":""},{"location":"cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"

Command definitions for the doc-forge CLI.

Provides the CLI structure using Click, including build, serve, and tree commands.

Notes "},{"location":"cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"cli/commands/#docforge.cli.commands.build","title":"build","text":"
build(\n    mcp: bool,\n    mkdocs: bool,\n    api: bool,\n    wiki: bool,\n    refresh: bool,\n    module_is_source: bool,\n    module: str | None,\n    openapi_spec: Path | None,\n    project_name: str | None,\n    site_name: str | None,\n    docs_dir: Path,\n    wiki_dir: Path,\n    nav_file: Path,\n    template: Path | None,\n    out_dir: Path,\n) -> None\n

Build documentation artifacts.

This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

Depending on the selected options, the build can target:

Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

Notes

Parameters:

Name Type Description Default mcp bool

Enable MCP documentation generation.

required mkdocs bool

Enable the lib MkDocs documentation generation.

required api bool

Enable API documentation generation from an OpenAPI spec.

required wiki bool

Build a hand-written wiki directory as its own MkDocs site.

required refresh bool

Regenerate docs/mkdocs.{kind}.yml from templates even when it already exists. By default, existing configs are used as-is.

required module_is_source bool

Treat the specified module directory as the project root.

required module str | None

Python module import path to document.

required openapi_spec Path | None

Path to the OpenAPI JSON specification used for API docs.

required project_name str | None

Optional override for the project name.

required site_name str | None

Display name for the lib and wiki MkDocs sites.

required docs_dir Path

Shared documentation root used for generated sources.

required wiki_dir Path

Directory containing hand-written wiki markdown files.

required nav_file Path

Path to the navigation specification file.

required template Path | None

Optional custom MkDocs configuration template.

required out_dir Path

Output directory for generated MCP resources.

required

Raises:

Type Description UsageError

If required options are missing or conflicting.

"},{"location":"cli/commands/#docforge.cli.commands.serve","title":"serve","text":"
serve(\n    mcp: bool,\n    mkdocs: bool,\n    lib: bool,\n    api: bool,\n    wiki: bool,\n    module: str | None,\n    mkdocs_yml: Path,\n    out_dir: Path,\n) -> None\n

Serve generated documentation locally.

Depending on the selected mode, this command starts either:

The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

Parameters:

Name Type Description Default mcp bool

Serve documentation using the MCP server.

required mkdocs bool

Serve the MkDocs development site from --mkdocs-yml.

required lib bool

Serve the lib MkDocs site.

required api bool

Serve the API MkDocs site.

required wiki bool

Serve the wiki MkDocs site.

required module str | None

Python module import path to serve via MCP.

required mkdocs_yml Path

Path to the MkDocs configuration file.

required out_dir Path

Root directory containing MCP documentation resources.

required

Raises:

Type Description UsageError

If invalid or conflicting options are provided.

"},{"location":"cli/commands/#docforge.cli.commands.tree","title":"tree","text":"
tree(module: str, project_name: str | None) -> None\n

Display the documentation object tree for a module.

This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

Parameters:

Name Type Description Default module str

Python module import path to introspect.

required project_name str | None

Optional name to display as the project root.

required"},{"location":"cli/main/","title":"Main","text":""},{"location":"cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"cli/main/#docforge.cli.main--summary","title":"Summary","text":"

Command-line entry point for the doc-forge CLI.

This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.

"},{"location":"cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"cli/main/#docforge.cli.main.main","title":"main","text":"
main() -> None\n

Run the doc-forge command-line interface.

This function initializes and executes the Click CLI application. It is used as the console entry point when invoking doc-forge from the command line.

"},{"location":"cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"

Utilities for working with MCP in the doc-forge CLI.

Notes "},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"
generate_resources(\n    module: str, project_name: str | None, out_dir: Path\n) -> None\n

Generate MCP documentation resources from a Python module.

The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.

Parameters:

Name Type Description Default module str

Python module import path used as the entry point for documentation generation.

required project_name str | None

Optional override for the project name used in generated documentation metadata.

required out_dir Path

Directory where MCP resources (index.json, nav.json, and module data) will be written.

required"},{"location":"cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"
serve(module: str, mcp_root: Path) -> None\n

Start an MCP server for a pre-generated documentation bundle.

The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.

Parameters:

Name Type Description Default module str

Python module import path used to identify the served documentation instance.

required mcp_root Path

Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).

required

Raises:

Type Description ClickException

If the MCP documentation bundle is missing required files or directories.

"},{"location":"cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"

Utilities for working with MkDocs in the doc-forge CLI.

Notes "},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"
build_configs(yml_paths: Iterable[Path]) -> None\n

Build the MkDocs documentation site for every given configuration.

Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

Parameters:

Name Type Description Default yml_paths Iterable[Path]

Configuration files to build, in order.

required

Raises:

Type Description ClickException

If a configuration file does not exist.

"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"
build_lib_nav(\n    nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n

Build the re-rooted navigation block for a lib site.

The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

Parameters:

Name Type Description Default nav_file Path

Path to the docforge.nav.yml navigation specification.

required docs_root Path

Shared documentation root containing the lib sources.

required

Returns:

Type Description tuple[list[dict[str, Any]], dict[str, str] | None]

tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

Raises:

Type Description FileError

If the navigation specification cannot be found.

"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"
build_wiki_nav_block(\n    wiki_dir: Path,\n) -> list[dict[str, Any]]\n

Build the re-rooted navigation block for a wiki site.

The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries relative to the wiki directory.

Raises:

Type Description FileError

If the wiki directory does not exist.

"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"
generate_site_config(\n    kind: str,\n    kind_root: Path,\n    nav_block: list[dict[str, Any]],\n    out: Path,\n    site_name: str,\n    docs_dir: str,\n    site_dir: str,\n    template: Path | None = None,\n    site_description: str | None = None,\n    site_author: str | None = None,\n    theme_icon: dict[str, str] | None = None,\n) -> None\n

Generate a per-kind mkdocs.{kind}.yml configuration file.

The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

Parameters:

Name Type Description Default kind str

Documentation kind, one of lib, api, or wiki.

required kind_root Path

Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.

required nav_block list[dict[str, Any]]

Re-rooted navigation entries for the kind's site.

required out Path

Destination path where the generated mkdocs.{kind}.yml file is written.

required site_name str

Display name for the generated documentation site.

required docs_dir str

MkDocs docs_dir value, relative to the configuration file's directory.

required site_dir str

MkDocs site_dir value, relative to the configuration file's directory.

required template Path | None

Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.

None site_description str | None

Optional site description written into the configuration.

None site_author str | None

Optional site author written into the configuration.

None theme_icon dict[str, str] | None

Optional mapping of theme icon entries injected as theme.icon.

None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
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

Generate MkDocs Markdown sources for a Python module.

This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

Parameters:

Name Type Description Default module str

Python module import path used as the entry point for documentation generation.

required docs_dir Path

Directory where the generated Markdown files will be written.

required project_name str | None

Optional override for the project name used in documentation metadata.

None module_is_source bool | None

If True, treat the specified module directory as the project root rather than a nested module.

None readme_dir Path | None

Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.

None"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"
load_spec_icon(nav_file: Path) -> dict[str, str] | None\n

Load the theme icon mapping from a navigation specification.

Parameters:

Name Type Description Default nav_file Path

Path to the navigation specification file.

required

Returns:

Type Description dict[str, str] | None

dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"
serve(mkdocs_yml: Path) -> None\n

Start an MkDocs development server with live reload.

The server watches documentation files and automatically reloads the site when changes are detected.

Parameters:

Name Type Description Default mkdocs_yml Path

Path to the mkdocs.yml configuration file.

required

Raises:

Type Description ClickException

If the configuration file does not exist.

"},{"location":"docforge/","title":"Docforge","text":""},{"location":"docforge/#docforge","title":"docforge","text":""},{"location":"docforge/#docforge--summary","title":"Summary","text":"

Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

doc-forge 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.

"},{"location":"docforge/#docforge--installation","title":"Installation","text":"

Install using pip:

pip install doc-forge\n
"},{"location":"docforge/#docforge--cli-usage","title":"CLI usage","text":"

Each site kind (lib, api, wiki) is built independently into site/{kind}.

"},{"location":"docforge/#docforge--build-the-library-reference-from-a-python-package","title":"Build the library reference from a Python package:","text":"
doc-forge build --mkdocs --module my_package\n
"},{"location":"docforge/#docforge--build-the-api-reference-from-an-openapi-spec","title":"Build the API reference from an OpenAPI spec:","text":"
doc-forge build --api --openapi-spec spec.json\n
"},{"location":"docforge/#docforge--build-the-hand-written-wiki","title":"Build the hand-written wiki:","text":"
doc-forge build --wiki --site-name my_package\n
"},{"location":"docforge/#docforge--generate-mcp-json-documentation","title":"Generate MCP JSON documentation:","text":"
doc-forge build --mcp --module my_package\n
"},{"location":"docforge/#docforge--build-several-kinds-in-one-pass","title":"Build several kinds in one pass:","text":"
doc-forge build --mcp --mkdocs --wiki --module my_package\n

Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/.

"},{"location":"docforge/#docforge--serve-a-site-locally","title":"Serve a site locally:","text":"
doc-forge serve --wiki        # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
"},{"location":"docforge/#docforge--serve-mcp-locally","title":"Serve MCP locally:","text":"
doc-forge serve --mcp --module my_package\n
"},{"location":"docforge/#docforge--core-concepts","title":"Core concepts","text":""},{"location":"docforge/#docforge--loader","title":"Loader","text":"

Extracts symbols, signatures, and docstrings using static analysis.

"},{"location":"docforge/#docforge--semantic-model","title":"Semantic model","text":"

Structured, renderer-agnostic representation of the API.

"},{"location":"docforge/#docforge--renderer","title":"Renderer","text":"

Converts the semantic model into output formats such as MkDocs or MCP JSON.

"},{"location":"docforge/#docforge--symbol","title":"Symbol","text":"

Any documentable object

"},{"location":"docforge/#docforge--architecture","title":"Architecture","text":"

doc-forge follows a compiler architecture:

"},{"location":"docforge/#docforge--front-end","title":"Front-end:","text":"

Static analysis of modules, classes, functions, type hints, and docstrings.

"},{"location":"docforge/#docforge--middle-end","title":"Middle-end:","text":"

Builds a semantic model describing symbols and relationships.

"},{"location":"docforge/#docforge--back-end","title":"Back-end:","text":"

Renders documentation using interchangeable renderers.

This architecture ensures deterministic documentation generation.

"},{"location":"docforge/#docforge--rendering-pipeline","title":"Rendering pipeline","text":"

Typical flow:

Python package\n    |\nLoader (static analysis)\n    |\nSemantic model\n    |\nRenderer\n    |\nMkDocs site or MCP JSON\n
"},{"location":"docforge/#docforge--google-styled-doc-forge-convention-gsdfc","title":"Google-Styled Doc-Forge Convention (GSDFC)","text":"

GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.

"},{"location":"docforge/#docforge--general-rules","title":"General rules","text":""},{"location":"docforge/#docforge--notes-subsection-grouping","title":"Notes subsection grouping","text":"

Group related information using labeled subsections.

Example:

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
"},{"location":"docforge/#docforge--example-formatting","title":"Example formatting","text":" Example

Single example:

Example:\n\n    ```python\n    foo = Foo(\"example\")\n    process(foo, multiplier=2)\n    ```\n

Multiple examples:

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

Avoid fenced code blocks inside argument descriptions and other prose lines.

Inside Example: sections, fenced python code blocks are allowed and must be indented four spaces, matching the examples below.

"},{"location":"docforge/#docforge--separator-rules","title":"Separator rules","text":"

Use horizontal separators only at docstring root level to separate sections:

---\n

Allowed locations:

Do not use separators inside code sections.

"},{"location":"docforge/#docforge--package-docstrings","title":"Package docstrings","text":"

Package docstrings act as the documentation home page.

Recommended sections:

# Summary\n# Installation\n# Quick start\n# CLI usage\n# Core concepts\n# Architecture\n# Rendering pipeline\n# Examples\n# Notes\n
Example

Package Doc String:

'''\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
"},{"location":"docforge/#docforge--module-docstrings","title":"Module docstrings","text":"

Module docstrings describe a subsystem.

Recommended sections:

# Summary\n# Examples\n# Notes\n
Example

Module Doc String:

'''\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
"},{"location":"docforge/#docforge--class-docstrings","title":"Class docstrings","text":"

Class docstrings define object responsibility, lifecycle, and attributes.

Recommended sections:

Attributes:\nNotes:\nExample:\nRaises:\n
Example

Simple Foo:

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

Complex Bar:

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
"},{"location":"docforge/#docforge--function-and-method-docstrings","title":"Function and method docstrings","text":"

Function docstrings define API contracts.

Recommended sections:

Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
Example

Simple process method:

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

Multiple Examples:

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
"},{"location":"docforge/#docforge--property-docstrings","title":"Property docstrings","text":"

Properties must document return values.

Example

Property Doc String:

```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
"},{"location":"docforge/#docforge--attribute-documentation","title":"Attribute documentation","text":"

Document attributes in class docstrings using Attributes:.

Example

Attribute Doc String:

```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
"},{"location":"docforge/#docforge--parsing-guarantees","title":"Parsing guarantees","text":"

GSDFC ensures doc-forge can deterministically extract:

This enables:

Notes "},{"location":"docforge/#docforge-classes","title":"Classes","text":""},{"location":"docforge/#docforge.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"docforge/#docforge.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/#docforge.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"docforge/#docforge.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"docforge/#docforge.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"docforge/#docforge.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"docforge/#docforge.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"docforge/#docforge.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/#docforge.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"docforge/#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"docforge/#docforge-functions","title":"Functions","text":""},{"location":"docforge/#docforge.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"docforge/cli/","title":"Cli","text":""},{"location":"docforge/cli/#docforge.cli","title":"docforge.cli","text":""},{"location":"docforge/cli/#docforge.cli--summary","title":"Summary","text":"

Command line interface entry point for doc-forge.

This module exposes the primary CLI entry function used by the doc-forge command. The actual command implementation resides in docforge.cli.main, while this module provides a stable import path for external tools and the package entry point configuration.

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.

"},{"location":"docforge/cli/#docforge.cli--typical-usage","title":"Typical usage","text":"

The CLI is normally invoked through the installed command:

doc-forge <command> [options]\n

Programmatic invocation is also possible:

Example:

```python\nfrom docforge.cli import main\nmain()\n```\n
"},{"location":"docforge/cli/api_utils/","title":"Api Utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils","title":"docforge.cli.api_utils","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils--summary","title":"Summary","text":"

Utilities for building API documentation from an OpenAPI specification.

"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.OpenAPIMetadata","title":"OpenAPIMetadata dataclass","text":"
OpenAPIMetadata(\n    site_name: str,\n    site_description: str | None,\n    site_author: str | None,\n)\n

Metadata derived from the info block of an OpenAPI specification.

Attributes:

Name Type Description site_name str

Spec title, used as the MkDocs site name.

site_description str | None

Spec description, used as the site description.

site_author str | None

Contact name (fallback: contact email), used as the site author.

"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.derive_metadata","title":"derive_metadata","text":"
derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata\n

Derive MkDocs site metadata from an OpenAPI spec info block.

Parameters:

Name Type Description Default spec dict

Parsed OpenAPI specification.

required

Returns:

Name Type Description OpenAPIMetadata OpenAPIMetadata

Site name, description, and author derived from the spec.

"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.generate_api_sources","title":"generate_api_sources","text":"
generate_api_sources(\n    spec: dict[Any, Any], docs_dir: Path\n) -> None\n

Generate swagger-enabled Markdown sources and the spec copy.

The specification is written as openapi.json inside docs_dir and an index.md embedding the swagger UI is generated alongside it.

Parameters:

Name Type Description Default spec dict

Parsed OpenAPI specification.

required docs_dir Path

Directory (for example docs/api) where the swagger sources are written.

required"},{"location":"docforge/cli/api_utils/#docforge.cli.api_utils.load_openapi_spec","title":"load_openapi_spec","text":"
load_openapi_spec(spec_path: Path) -> dict[Any, Any]\n

Load and validate an OpenAPI specification from a JSON file.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI JSON specification file.

required

Returns:

Name Type Description dict dict[Any, Any]

The parsed OpenAPI specification.

Raises:

Type Description ClickException

If the file cannot be read or the info block is invalid.

"},{"location":"docforge/cli/commands/","title":"Commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands","title":"docforge.cli.commands","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands--summary","title":"Summary","text":"

Command definitions for the doc-forge CLI.

Provides the CLI structure using Click, including build, serve, and tree commands.

Notes "},{"location":"docforge/cli/commands/#docforge.cli.commands-classes","title":"Classes","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands-functions","title":"Functions","text":""},{"location":"docforge/cli/commands/#docforge.cli.commands.build","title":"build","text":"
build(\n    mcp: bool,\n    mkdocs: bool,\n    api: bool,\n    wiki: bool,\n    refresh: bool,\n    module_is_source: bool,\n    module: str | None,\n    openapi_spec: Path | None,\n    project_name: str | None,\n    site_name: str | None,\n    docs_dir: Path,\n    wiki_dir: Path,\n    nav_file: Path,\n    template: Path | None,\n    out_dir: Path,\n) -> None\n

Build documentation artifacts.

This command runs the full documentation pipeline: it loads Python modules, generates renderer-specific documentation sources, and optionally builds the final output.

Depending on the selected options, the build can target:

Each enabled site kind produces its own MkDocs configuration (docs/mkdocs.{kind}.yml) and its own build (site/{kind}).

Notes

Parameters:

Name Type Description Default mcp bool

Enable MCP documentation generation.

required mkdocs bool

Enable the lib MkDocs documentation generation.

required api bool

Enable API documentation generation from an OpenAPI spec.

required wiki bool

Build a hand-written wiki directory as its own MkDocs site.

required refresh bool

Regenerate docs/mkdocs.{kind}.yml from templates even when it already exists. By default, existing configs are used as-is.

required module_is_source bool

Treat the specified module directory as the project root.

required module str | None

Python module import path to document.

required openapi_spec Path | None

Path to the OpenAPI JSON specification used for API docs.

required project_name str | None

Optional override for the project name.

required site_name str | None

Display name for the lib and wiki MkDocs sites.

required docs_dir Path

Shared documentation root used for generated sources.

required wiki_dir Path

Directory containing hand-written wiki markdown files.

required nav_file Path

Path to the navigation specification file.

required template Path | None

Optional custom MkDocs configuration template.

required out_dir Path

Output directory for generated MCP resources.

required

Raises:

Type Description UsageError

If required options are missing or conflicting.

"},{"location":"docforge/cli/commands/#docforge.cli.commands.serve","title":"serve","text":"
serve(\n    mcp: bool,\n    mkdocs: bool,\n    lib: bool,\n    api: bool,\n    wiki: bool,\n    module: str | None,\n    mkdocs_yml: Path,\n    out_dir: Path,\n) -> None\n

Serve generated documentation locally.

Depending on the selected mode, this command starts either:

The kind flags (--lib, --api, --wiki) select the generated per-kind config (docs/mkdocs.{kind}.yml); --mkdocs serves the config passed via --mkdocs-yml.

Parameters:

Name Type Description Default mcp bool

Serve documentation using the MCP server.

required mkdocs bool

Serve the MkDocs development site from --mkdocs-yml.

required lib bool

Serve the lib MkDocs site.

required api bool

Serve the API MkDocs site.

required wiki bool

Serve the wiki MkDocs site.

required module str | None

Python module import path to serve via MCP.

required mkdocs_yml Path

Path to the MkDocs configuration file.

required out_dir Path

Root directory containing MCP documentation resources.

required

Raises:

Type Description UsageError

If invalid or conflicting options are provided.

"},{"location":"docforge/cli/commands/#docforge.cli.commands.tree","title":"tree","text":"
tree(module: str, project_name: str | None) -> None\n

Display the documentation object tree for a module.

This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.

Parameters:

Name Type Description Default module str

Python module import path to introspect.

required project_name str | None

Optional name to display as the project root.

required"},{"location":"docforge/cli/main/","title":"Main","text":""},{"location":"docforge/cli/main/#docforge.cli.main","title":"docforge.cli.main","text":""},{"location":"docforge/cli/main/#docforge.cli.main--summary","title":"Summary","text":"

Command-line entry point for the doc-forge CLI.

This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.

"},{"location":"docforge/cli/main/#docforge.cli.main-functions","title":"Functions","text":""},{"location":"docforge/cli/main/#docforge.cli.main.main","title":"main","text":"
main() -> None\n

Run the doc-forge command-line interface.

This function initializes and executes the Click CLI application. It is used as the console entry point when invoking doc-forge from the command line.

"},{"location":"docforge/cli/mcp_utils/","title":"Mcp Utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils","title":"docforge.cli.mcp_utils","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils--summary","title":"Summary","text":"

Utilities for working with MCP in the doc-forge CLI.

Notes "},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.generate_resources","title":"generate_resources","text":"
generate_resources(\n    module: str, project_name: str | None, out_dir: Path\n) -> None\n

Generate MCP documentation resources from a Python module.

The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.

Parameters:

Name Type Description Default module str

Python module import path used as the entry point for documentation generation.

required project_name str | None

Optional override for the project name used in generated documentation metadata.

required out_dir Path

Directory where MCP resources (index.json, nav.json, and module data) will be written.

required"},{"location":"docforge/cli/mcp_utils/#docforge.cli.mcp_utils.serve","title":"serve","text":"
serve(module: str, mcp_root: Path) -> None\n

Start an MCP server for a pre-generated documentation bundle.

The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.

Parameters:

Name Type Description Default module str

Python module import path used to identify the served documentation instance.

required mcp_root Path

Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).

required

Raises:

Type Description ClickException

If the MCP documentation bundle is missing required files or directories.

"},{"location":"docforge/cli/mkdocs_utils/","title":"Mkdocs Utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils","title":"docforge.cli.mkdocs_utils","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils--summary","title":"Summary","text":"

Utilities for working with MkDocs in the doc-forge CLI.

Notes "},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-classes","title":"Classes","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils-functions","title":"Functions","text":""},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_configs","title":"build_configs","text":"
build_configs(yml_paths: Iterable[Path]) -> None\n

Build the MkDocs documentation site for every given configuration.

Each configuration file is loaded and built in turn, producing the per-kind static sites (site/lib, site/api, site/wiki).

Parameters:

Name Type Description Default yml_paths Iterable[Path]

Configuration files to build, in order.

required

Raises:

Type Description ClickException

If a configuration file does not exist.

"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_lib_nav","title":"build_lib_nav","text":"
build_lib_nav(\n    nav_file: Path, docs_root: Path\n) -> tuple[list[dict[str, Any]], dict[str, str] | None]\n

Build the re-rooted navigation block for a lib site.

The navigation specification is resolved against the shared documentation root and every resulting path is re-rooted relative to the lib subdirectory by stripping its leading lib/ scope component.

Parameters:

Name Type Description Default nav_file Path

Path to the docforge.nav.yml navigation specification.

required docs_root Path

Shared documentation root containing the lib sources.

required

Returns:

Type Description tuple[list[dict[str, Any]], dict[str, str] | None]

tuple[list[dict[str, Any]], dict[str, str] | None]: The re-rooted navigation block and the optional theme icon mapping from the specification.

Raises:

Type Description FileError

If the navigation specification cannot be found.

"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.build_wiki_nav_block","title":"build_wiki_nav_block","text":"
build_wiki_nav_block(\n    wiki_dir: Path,\n) -> list[dict[str, Any]]\n

Build the re-rooted navigation block for a wiki site.

The wiki navigation derived from the wiki file structure is re-rooted relative to the wiki directory itself by stripping the leading wiki/ scope component.

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries relative to the wiki directory.

Raises:

Type Description FileError

If the wiki directory does not exist.

"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_site_config","title":"generate_site_config","text":"
generate_site_config(\n    kind: str,\n    kind_root: Path,\n    nav_block: list[dict[str, Any]],\n    out: Path,\n    site_name: str,\n    docs_dir: str,\n    site_dir: str,\n    template: Path | None = None,\n    site_description: str | None = None,\n    site_author: str | None = None,\n    theme_icon: dict[str, str] | None = None,\n) -> None\n

Generate a per-kind mkdocs.{kind}.yml configuration file.

The configuration is created by merging the shared mkdocs.common.yml template with the fragment contributed by the kind (lib, api, or wiki). Both docs_dir and site_dir are written relative to the configuration file's directory: the kind's sources when expressed as a sibling path (for example lib) and the per-kind site output (for example ../site/lib).

Parameters:

Name Type Description Default kind str

Documentation kind, one of lib, api, or wiki.

required kind_root Path

Directory scoped to the kind (for example docs/lib) that serves as the MkDocs docs_dir.

required nav_block list[dict[str, Any]]

Re-rooted navigation entries for the kind's site.

required out Path

Destination path where the generated mkdocs.{kind}.yml file is written.

required site_name str

Display name for the generated documentation site.

required docs_dir str

MkDocs docs_dir value, relative to the configuration file's directory.

required site_dir str

MkDocs site_dir value, relative to the configuration file's directory.

required template Path | None

Optional path to a fully custom MkDocs configuration template that replaces the built-in templates entirely.

None site_description str | None

Optional site description written into the configuration.

None site_author str | None

Optional site author written into the configuration.

None theme_icon dict[str, str] | None

Optional mapping of theme icon entries injected as theme.icon.

None"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
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

Generate MkDocs Markdown sources for a Python module.

This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.

Parameters:

Name Type Description Default module str

Python module import path used as the entry point for documentation generation.

required docs_dir Path

Directory where the generated Markdown files will be written.

required project_name str | None

Optional override for the project name used in documentation metadata.

None module_is_source bool | None

If True, treat the specified module directory as the project root rather than a nested module.

None readme_dir Path | None

Directory where the generated README.md should be written. If not provided, defaults to the parent of docs_dir.

None"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.load_spec_icon","title":"load_spec_icon","text":"
load_spec_icon(nav_file: Path) -> dict[str, str] | None\n

Load the theme icon mapping from a navigation specification.

Parameters:

Name Type Description Default nav_file Path

Path to the navigation specification file.

required

Returns:

Type Description dict[str, str] | None

dict[str, str] | None: The icon mapping, or None when the specification file is absent or cannot be parsed.

"},{"location":"docforge/cli/mkdocs_utils/#docforge.cli.mkdocs_utils.serve","title":"serve","text":"
serve(mkdocs_yml: Path) -> None\n

Start an MkDocs development server with live reload.

The server watches documentation files and automatically reloads the site when changes are detected.

Parameters:

Name Type Description Default mkdocs_yml Path

Path to the mkdocs.yml configuration file.

required

Raises:

Type Description ClickException

If the configuration file does not exist.

"},{"location":"docforge/loaders/","title":"Loaders","text":""},{"location":"docforge/loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"docforge/loaders/#docforge.loaders--summary","title":"Summary","text":"

Loader layer for doc-forge.

The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

"},{"location":"docforge/loaders/#docforge.loaders--overview","title":"Overview","text":"

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.

Core capabilities include:

"},{"location":"docforge/loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"docforge/loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"docforge/loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"docforge/loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"docforge/loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"

Utilities for loading and introspecting Python modules using Griffe.

This module provides the GriffeLoader class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models.

Notes "},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"docforge/loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"docforge/models/","title":"Models","text":""},{"location":"docforge/models/#docforge.models","title":"docforge.models","text":""},{"location":"docforge/models/#docforge.models--summary","title":"Summary","text":"

Model layer for doc-forge.

The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

"},{"location":"docforge/models/#docforge.models--overview","title":"Overview","text":"

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.

Key components:

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).

"},{"location":"docforge/models/#docforge.models-classes","title":"Classes","text":""},{"location":"docforge/models/#docforge.models.DocObject","title":"DocObject","text":"
DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

Representation of a documented Python object.

A DocObject 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.

Attributes:

Name Type Description name str

Local name of the object.

kind str

Type of object (for example class, function, method, or attribute).

path str

Fully qualified dotted path to the object.

signature str | None

Callable signature if the object represents a callable.

docstring str | None

Raw docstring text extracted from the source code.

members dict[str, DocObject]

Mapping of member names to child DocObject instances.

Initialize a DocObject instance.

Parameters:

Name Type Description Default name str

Local name of the object.

required kind str

Object type identifier (for example class or function).

required path str

Fully qualified dotted path of the object.

required signature str | None

Callable signature if applicable.

None docstring str | None

Documentation string associated with the object.

None"},{"location":"docforge/models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.DocObject.add_member","title":"add_member","text":"
add_member(obj: DocObject) -> None\n

Add a child documentation object.

This is typically used when attaching methods to classes or nested objects to their parent containers.

Parameters:

Name Type Description Default obj DocObject

Documentation object to add as a member.

required"},{"location":"docforge/models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"
get_all_members() -> Iterable[DocObject]\n

Return all child members of the object.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing nested members.

"},{"location":"docforge/models/#docforge.models.DocObject.get_member","title":"get_member","text":"
get_member(name: str) -> DocObject\n

Retrieve a member object by name.

Parameters:

Name Type Description Default name str

Name of the member to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If the member does not exist.

"},{"location":"docforge/models/#docforge.models.Module","title":"Module","text":"
Module(path: str, docstring: str | None = None)\n

Representation of a documented Python module or package.

A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

Attributes:

Name Type Description path str

Dotted import path of the module.

docstring str | None

Module-level documentation string, if present.

members dict[str, DocObject]

Mapping of object names to their corresponding DocObject representations.

Initialize a Module instance.

Parameters:

Name Type Description Default path str

Dotted import path identifying the module.

required docstring str | None

Module-level documentation text, if available.

None"},{"location":"docforge/models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Module.add_object","title":"add_object","text":"
add_object(obj: DocObject) -> None\n

Add a documented object to the module.

Parameters:

Name Type Description Default obj DocObject

Documentation object to register as a top-level member of the module.

required"},{"location":"docforge/models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"
get_all_objects() -> Iterable[DocObject]\n

Return all top-level documentation objects in the module.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

"},{"location":"docforge/models/#docforge.models.Module.get_object","title":"get_object","text":"
get_object(name: str) -> DocObject\n

Retrieve a documented object by name.

Parameters:

Name Type Description Default name str

Name of the object to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If no object with the given name exists.

"},{"location":"docforge/models/#docforge.models.Project","title":"Project","text":"
Project(name: str)\n

Representation of a documentation project.

A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

Attributes:

Name Type Description name str

Name of the project.

modules dict[str, Module]

Mapping of module paths to Module instances.

Initialize a Project instance.

Parameters:

Name Type Description Default name str

Name used to identify the documentation project.

required Example

Create a project and register a module:

```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
"},{"location":"docforge/models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"docforge/models/#docforge.models.Project.add_module","title":"add_module","text":"
add_module(module: Module) -> None\n

Register a module in the project.

Parameters:

Name Type Description Default module Module

Module instance to add to the project.

required"},{"location":"docforge/models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"
get_all_modules() -> Iterable[Module]\n

Return all modules contained in the project.

Returns:

Type Description Iterable[Module]

Iterable[Module]: An iterable of Module instances.

"},{"location":"docforge/models/#docforge.models.Project.get_module","title":"get_module","text":"
get_module(path: str) -> Module\n

Retrieve a module by its dotted path.

Parameters:

Name Type Description Default path str

Fully qualified dotted module path (for example pkg.module).

required

Returns:

Name Type Description Module Module

The corresponding Module instance.

Raises:

Type Description KeyError

If the module does not exist in the project.

"},{"location":"docforge/models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"
get_module_list() -> list[str]\n

Return the list of module import paths.

Returns:

Type Description list[str]

list[str]: A list containing the dotted paths of all modules in the project.

"},{"location":"docforge/models/module/","title":"Module","text":""},{"location":"docforge/models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"docforge/models/module/#docforge.models.module--summary","title":"Summary","text":"

Documentation model representing a Python module or package.

This module defines the Module class used in the doc-forge documentation model. A Module acts as a container for top-level documented objects (classes, functions, variables, and other members) discovered during introspection.

Notes "},{"location":"docforge/models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"docforge/models/module/#docforge.models.module.Module","title":"Module","text":"
Module(path: str, docstring: str | None = None)\n

Representation of a documented Python module or package.

A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

Attributes:

Name Type Description path str

Dotted import path of the module.

docstring str | None

Module-level documentation string, if present.

members dict[str, DocObject]

Mapping of object names to their corresponding DocObject representations.

Initialize a Module instance.

Parameters:

Name Type Description Default path str

Dotted import path identifying the module.

required docstring str | None

Module-level documentation text, if available.

None"},{"location":"docforge/models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"docforge/models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"
add_object(obj: DocObject) -> None\n

Add a documented object to the module.

Parameters:

Name Type Description Default obj DocObject

Documentation object to register as a top-level member of the module.

required"},{"location":"docforge/models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"
get_all_objects() -> Iterable[DocObject]\n

Return all top-level documentation objects in the module.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

"},{"location":"docforge/models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"
get_object(name: str) -> DocObject\n

Retrieve a documented object by name.

Parameters:

Name Type Description Default name str

Name of the object to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If no object with the given name exists.

"},{"location":"docforge/models/object/","title":"Object","text":""},{"location":"docforge/models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"docforge/models/object/#docforge.models.object--summary","title":"Summary","text":"

Documentation model representing individual Python objects.

This module defines the DocObject class, the fundamental recursive unit of the doc-forge documentation model. Each DocObject represents a Python entity such as a class, function, method, or attribute, and may contain nested members that form a hierarchical documentation structure.

Notes "},{"location":"docforge/models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

Representation of a documented Python object.

A DocObject 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.

Attributes:

Name Type Description name str

Local name of the object.

kind str

Type of object (for example class, function, method, or attribute).

path str

Fully qualified dotted path to the object.

signature str | None

Callable signature if the object represents a callable.

docstring str | None

Raw docstring text extracted from the source code.

members dict[str, DocObject]

Mapping of member names to child DocObject instances.

Initialize a DocObject instance.

Parameters:

Name Type Description Default name str

Local name of the object.

required kind str

Object type identifier (for example class or function).

required path str

Fully qualified dotted path of the object.

required signature str | None

Callable signature if applicable.

None docstring str | None

Documentation string associated with the object.

None"},{"location":"docforge/models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"docforge/models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"
add_member(obj: DocObject) -> None\n

Add a child documentation object.

This is typically used when attaching methods to classes or nested objects to their parent containers.

Parameters:

Name Type Description Default obj DocObject

Documentation object to add as a member.

required"},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"
get_all_members() -> Iterable[DocObject]\n

Return all child members of the object.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing nested members.

"},{"location":"docforge/models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"
get_member(name: str) -> DocObject\n

Retrieve a member object by name.

Parameters:

Name Type Description Default name str

Name of the member to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If the member does not exist.

"},{"location":"docforge/models/project/","title":"Project","text":""},{"location":"docforge/models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"docforge/models/project/#docforge.models.project--summary","title":"Summary","text":"

Documentation model representing a project.

This module defines the Project class, the top-level container used by doc-forge to represent a documented codebase. A Project aggregates multiple modules and provides access to them through a unified interface.

Notes "},{"location":"docforge/models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"docforge/models/project/#docforge.models.project.Project","title":"Project","text":"
Project(name: str)\n

Representation of a documentation project.

A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

Attributes:

Name Type Description name str

Name of the project.

modules dict[str, Module]

Mapping of module paths to Module instances.

Initialize a Project instance.

Parameters:

Name Type Description Default name str

Name used to identify the documentation project.

required Example

Create a project and register a module:

```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
"},{"location":"docforge/models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"docforge/models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"
add_module(module: Module) -> None\n

Register a module in the project.

Parameters:

Name Type Description Default module Module

Module instance to add to the project.

required"},{"location":"docforge/models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"
get_all_modules() -> Iterable[Module]\n

Return all modules contained in the project.

Returns:

Type Description Iterable[Module]

Iterable[Module]: An iterable of Module instances.

"},{"location":"docforge/models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"
get_module(path: str) -> Module\n

Retrieve a module by its dotted path.

Parameters:

Name Type Description Default path str

Fully qualified dotted module path (for example pkg.module).

required

Returns:

Name Type Description Module Module

The corresponding Module instance.

Raises:

Type Description KeyError

If the module does not exist in the project.

"},{"location":"docforge/models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"
get_module_list() -> list[str]\n

Return the list of module import paths.

Returns:

Type Description list[str]

list[str]: A list containing the dotted paths of all modules in the project.

"},{"location":"docforge/nav/","title":"Nav","text":""},{"location":"docforge/nav/#docforge.nav","title":"docforge.nav","text":"

Navigation layer for doc-forge.

The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

"},{"location":"docforge/nav/#docforge.nav--workflow","title":"Workflow","text":"
  1. Specification \u2013 Users define navigation intent in docforge.nav.yml.
  2. Resolution \u2013 resolve_nav expands patterns and matches them against generated Markdown files.
  3. Emission \u2013 MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

"},{"location":"docforge/nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

"},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"
emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

Generate a navigation structure for mkdocs.yml.

Parameters:

Name Type Description Default nav ResolvedNav

Resolved navigation data describing documentation groups and their associated Markdown files.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.

"},{"location":"docforge/nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

Parsed representation of a navigation specification.

A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page (for example index.md).

groups dict[str, list[str]]

Mapping of navigation group titles to lists of file patterns or glob expressions.

icon

Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home document.

required groups dict[str, list[str]]

Mapping of group names to lists of path patterns (glob expressions).

required icon dict[str, str] | None

Optional mapping of theme icon entries applied to the generated MkDocs configuration.

None"},{"location":"docforge/nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"
all_patterns() -> list[str]\n

Return all path patterns referenced by the specification.

Returns:

Type Description list[str]

list[str]: A list containing the home document (if defined) and all group pattern entries.

"},{"location":"docforge/nav/#docforge.nav.NavSpec.load","title":"load classmethod","text":"
load(path: Path) -> NavSpec\n

Load a navigation specification from a YAML file.

Parameters:

Name Type Description Default path Path

Filesystem path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed configuration.

Raises:

Type Description FileNotFoundError

If the specified file does not exist.

ValueError

If the file contents are not a valid navigation specification.

"},{"location":"docforge/nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"
ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page.

groups dict[str, list[Path]]

Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home page within the documentation root.

required groups dict[str, list[Path]]

Mapping of group titles to resolved documentation file paths.

required docs_root Path | None

Root directory of the documentation source files.

None"},{"location":"docforge/nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"
all_files() -> Iterable[Path]\n

Iterate over all files referenced by the navigation structure.

Yields:

Name Type Description Path Iterable[Path]

A documentation file referenced by the navigation, including the home page when defined.

Raises:

Type Description RuntimeError

If the home page is defined but the documentation root is not available for resolution.

"},{"location":"docforge/nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"docforge/nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

Derive an MkDocs navigation block from a wiki directory.

Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries compatible with the MkDocs nav configuration. The list is empty if the wiki contains no Markdown files.

Raises:

Type Description FileNotFoundError

If the wiki directory does not exist.

"},{"location":"docforge/nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"
load_nav_spec(path: Path) -> NavSpec\n

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

Parameters:

Name Type Description Default path Path

Path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed specification.

Raises:

Type Description FileNotFoundError

If the specification file does not exist.

ValueError

If the YAML structure is invalid.

"},{"location":"docforge/nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name Type Description Default spec NavSpec

Navigation specification describing documentation layout.

required docs_root Path

Root directory containing documentation Markdown files.

required

Returns:

Name Type Description ResolvedNav ResolvedNav

A ResolvedNav instance containing validated navigation paths.

Raises:

Type Description FileNotFoundError

If the documentation root does not exist or a navigation pattern does not match any files.

"},{"location":"docforge/nav/mkdocs/","title":"Mkdocs","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"

MkDocs navigation emitter.

This module provides the MkDocsNavEmitter class, which converts a ResolvedNav instance into the navigation structure required by the MkDocs nav configuration.

Notes "},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

"},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"docforge/nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"
emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

Generate a navigation structure for mkdocs.yml.

Parameters:

Name Type Description Default nav ResolvedNav

Resolved navigation data describing documentation groups and their associated Markdown files.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.

"},{"location":"docforge/nav/resolver/","title":"Resolver","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"

Navigation resolution utilities.

This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

Notes "},{"location":"docforge/nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page.

groups dict[str, list[Path]]

Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home page within the documentation root.

required groups dict[str, list[Path]]

Mapping of group titles to resolved documentation file paths.

required docs_root Path | None

Root directory of the documentation source files.

None"},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"
all_files() -> Iterable[Path]\n

Iterate over all files referenced by the navigation structure.

Yields:

Name Type Description Path Iterable[Path]

A documentation file referenced by the navigation, including the home page when defined.

Raises:

Type Description RuntimeError

If the home page is defined but the documentation root is not available for resolution.

"},{"location":"docforge/nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"docforge/nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name Type Description Default spec NavSpec

Navigation specification describing documentation layout.

required docs_root Path

Root directory containing documentation Markdown files.

required

Returns:

Name Type Description ResolvedNav ResolvedNav

A ResolvedNav instance containing validated navigation paths.

Raises:

Type Description FileNotFoundError

If the documentation root does not exist or a navigation pattern does not match any files.

"},{"location":"docforge/nav/spec/","title":"Spec","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"

Navigation specification model.

This module defines the NavSpec class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically docforge.nav.yml).

Notes "},{"location":"docforge/nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

Parsed representation of a navigation specification.

A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page (for example index.md).

groups dict[str, list[str]]

Mapping of navigation group titles to lists of file patterns or glob expressions.

icon

Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home document.

required groups dict[str, list[str]]

Mapping of group names to lists of path patterns (glob expressions).

required icon dict[str, str] | None

Optional mapping of theme icon entries applied to the generated MkDocs configuration.

None"},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"
all_patterns() -> list[str]\n

Return all path patterns referenced by the specification.

Returns:

Type Description list[str]

list[str]: A list containing the home document (if defined) and all group pattern entries.

"},{"location":"docforge/nav/spec/#docforge.nav.spec.NavSpec.load","title":"load classmethod","text":"
load(path: Path) -> NavSpec\n

Load a navigation specification from a YAML file.

Parameters:

Name Type Description Default path Path

Filesystem path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed configuration.

Raises:

Type Description FileNotFoundError

If the specified file does not exist.

ValueError

If the file contents are not a valid navigation specification.

"},{"location":"docforge/nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"docforge/nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"
load_nav_spec(path: Path) -> NavSpec\n

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

Parameters:

Name Type Description Default path Path

Path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed specification.

Raises:

Type Description FileNotFoundError

If the specification file does not exist.

ValueError

If the YAML structure is invalid.

"},{"location":"docforge/nav/wiki/","title":"Wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"

Wiki navigation derivation.

This module provides build_wiki_nav, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically docs/wiki). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.

"},{"location":"docforge/nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"docforge/nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

Derive an MkDocs navigation block from a wiki directory.

Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries compatible with the MkDocs nav configuration. The list is empty if the wiki contains no Markdown files.

Raises:

Type Description FileNotFoundError

If the wiki directory does not exist.

"},{"location":"docforge/renderers/","title":"Renderers","text":""},{"location":"docforge/renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"docforge/renderers/#docforge.renderers--summary","title":"Summary","text":"

Renderers layer for doc-forge.

The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.

"},{"location":"docforge/renderers/#docforge.renderers--overview","title":"Overview","text":"

Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

Current implementations:

"},{"location":"docforge/renderers/#docforge.renderers--extending","title":"Extending","text":"

New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.

"},{"location":"docforge/renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"docforge/renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"docforge/renderers/base/","title":"Base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"

Renderer base interfaces and configuration models.

This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.

"},{"location":"docforge/renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"

Bases: Protocol

Protocol defining the interface for documentation renderers.

Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.

"},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate renderer-specific documentation sources.

Parameters:

Name Type Description Default project Project

Project model containing modules and documentation objects.

required out_dir Path

Directory where generated documentation sources should be written.

required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"
RendererConfig(out_dir: Path, project: Project)\n

Configuration container for documentation renderers.

A RendererConfig instance groups together the project model and the output directory used during rendering.

Attributes:

Name Type Description out_dir Path

Directory where generated documentation files will be written.

project Project

Documentation project model to be rendered.

Initialize a RendererConfig instance.

Parameters:

Name Type Description Default out_dir Path

Target directory where documentation files should be written.

required project Project

Introspected project model to render.

required"},{"location":"docforge/renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"

MCP renderer implementation.

This module defines the MCPRenderer class, which generates documentation resources compatible with the Model Context Protocol (MCP).

"},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"docforge/renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"

MkDocs renderer implementation.

This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

The renderer ensures a consistent documentation structure by:

"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"docforge/renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"docforge/servers/","title":"Servers","text":""},{"location":"docforge/servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"docforge/servers/#docforge.servers--summary","title":"Summary","text":"

Server layer for doc-forge.

This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.

"},{"location":"docforge/servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer","title":"MCPServer","text":"
MCPServer(mcp_root: Path, name: str)\n

MCP server for serving a pre-generated documentation bundle.

The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

Attributes:

Name Type Description mcp_root Path

Directory containing the generated MCP documentation bundle.

app FastMCP

Underlying FastMCP application instance that registers resources and tools.

Initialize the MCP server.

Parameters:

Name Type Description Default mcp_root Path

Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

required name str

Identifier used for the MCP server instance.

required"},{"location":"docforge/servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/#docforge.servers.MCPServer.run","title":"run","text":"
run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

Start the MCP server.

Parameters:

Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

'streamable-http'"},{"location":"docforge/servers/mcp_server/","title":"Mcp Server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"

MCP server implementation.

This module defines the MCPServer class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).

Notes "},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"
MCPServer(mcp_root: Path, name: str)\n

MCP server for serving a pre-generated documentation bundle.

The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

Attributes:

Name Type Description mcp_root Path

Directory containing the generated MCP documentation bundle.

app FastMCP

Underlying FastMCP application instance that registers resources and tools.

Initialize the MCP server.

Parameters:

Name Type Description Default mcp_root Path

Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

required name str

Identifier used for the MCP server instance.

required"},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"docforge/servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"
run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

Start the MCP server.

Parameters:

Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

'streamable-http'"},{"location":"loaders/","title":"Loaders","text":""},{"location":"loaders/#docforge.loaders","title":"docforge.loaders","text":""},{"location":"loaders/#docforge.loaders--summary","title":"Summary","text":"

Loader layer for doc-forge.

The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

"},{"location":"loaders/#docforge.loaders--overview","title":"Overview","text":"

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.

Core capabilities include:

"},{"location":"loaders/#docforge.loaders-classes","title":"Classes","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"loaders/#docforge.loaders.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"loaders/#docforge.loaders-functions","title":"Functions","text":""},{"location":"loaders/#docforge.loaders.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"loaders/griffe_loader/","title":"Griffe Loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader","title":"docforge.loaders.griffe_loader","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader--summary","title":"Summary","text":"

Utilities for loading and introspecting Python modules using Griffe.

This module provides the GriffeLoader class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models.

Notes "},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-classes","title":"Classes","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader","title":"GriffeLoader","text":"
GriffeLoader()\n

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Attributes:

Name Type Description _loader GriffeLoader

Internal Griffe loader with dedicated module and line collections.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_module","title":"load_module","text":"
load_module(path: str) -> Module\n

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name Type Description Default path str

Dotted import path of the module.

required

Returns:

Name Type Description Module Module

A populated Module instance.

Raises:

Type Description ImportError

If the module cannot be loaded by Griffe.

KeyError

If the loaded module is missing from the module collection.

Example

Load a single module:

```python\nloader = GriffeLoader()\nmodule = loader.load_module(\"mypackage.submodule\")\n```\n
"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
load_project(\n    module_paths: list[str],\n    project_name: str | None = None,\n    skip_import_errors: bool | None = None,\n) -> Project\n

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name Type Description Default module_paths list[str]

List of dotted module import paths to load.

required project_name str | None

Optional override for the project name. Defaults to the top-level name of the first module.

None skip_import_errors bool | None

If True, modules that fail to load will be skipped instead of raising an error.

None

Returns:

Name Type Description Project Project

A populated Project instance containing the loaded modules.

Raises:

Type Description ValueError

If no module paths are provided.

ImportError

If a module fails to load and skip_import_errors is False.

"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader-functions","title":"Functions","text":""},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.discover_module_paths","title":"discover_module_paths","text":"
discover_module_paths(\n    module_name: str, project_root: Path | None = None\n) -> list[str]\n

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Parameters:

Name Type Description Default module_name str

Top-level package name to discover modules from.

required project_root Path | None

Root directory used to resolve module paths. If not provided, the current working directory is used.

None

Returns:

Type Description list[str]

list[str]: A sorted list of unique dotted module import paths.

Raises:

Type Description FileNotFoundError

If the specified package directory does not exist.

"},{"location":"models/","title":"Models","text":""},{"location":"models/#docforge.models","title":"docforge.models","text":""},{"location":"models/#docforge.models--summary","title":"Summary","text":"

Model layer for doc-forge.

The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

"},{"location":"models/#docforge.models--overview","title":"Overview","text":"

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.

Key components:

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).

"},{"location":"models/#docforge.models-classes","title":"Classes","text":""},{"location":"models/#docforge.models.DocObject","title":"DocObject","text":"
DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

Representation of a documented Python object.

A DocObject 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.

Attributes:

Name Type Description name str

Local name of the object.

kind str

Type of object (for example class, function, method, or attribute).

path str

Fully qualified dotted path to the object.

signature str | None

Callable signature if the object represents a callable.

docstring str | None

Raw docstring text extracted from the source code.

members dict[str, DocObject]

Mapping of member names to child DocObject instances.

Initialize a DocObject instance.

Parameters:

Name Type Description Default name str

Local name of the object.

required kind str

Object type identifier (for example class or function).

required path str

Fully qualified dotted path of the object.

required signature str | None

Callable signature if applicable.

None docstring str | None

Documentation string associated with the object.

None"},{"location":"models/#docforge.models.DocObject-functions","title":"Functions","text":""},{"location":"models/#docforge.models.DocObject.add_member","title":"add_member","text":"
add_member(obj: DocObject) -> None\n

Add a child documentation object.

This is typically used when attaching methods to classes or nested objects to their parent containers.

Parameters:

Name Type Description Default obj DocObject

Documentation object to add as a member.

required"},{"location":"models/#docforge.models.DocObject.get_all_members","title":"get_all_members","text":"
get_all_members() -> Iterable[DocObject]\n

Return all child members of the object.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing nested members.

"},{"location":"models/#docforge.models.DocObject.get_member","title":"get_member","text":"
get_member(name: str) -> DocObject\n

Retrieve a member object by name.

Parameters:

Name Type Description Default name str

Name of the member to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If the member does not exist.

"},{"location":"models/#docforge.models.Module","title":"Module","text":"
Module(path: str, docstring: str | None = None)\n

Representation of a documented Python module or package.

A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

Attributes:

Name Type Description path str

Dotted import path of the module.

docstring str | None

Module-level documentation string, if present.

members dict[str, DocObject]

Mapping of object names to their corresponding DocObject representations.

Initialize a Module instance.

Parameters:

Name Type Description Default path str

Dotted import path identifying the module.

required docstring str | None

Module-level documentation text, if available.

None"},{"location":"models/#docforge.models.Module-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Module.add_object","title":"add_object","text":"
add_object(obj: DocObject) -> None\n

Add a documented object to the module.

Parameters:

Name Type Description Default obj DocObject

Documentation object to register as a top-level member of the module.

required"},{"location":"models/#docforge.models.Module.get_all_objects","title":"get_all_objects","text":"
get_all_objects() -> Iterable[DocObject]\n

Return all top-level documentation objects in the module.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

"},{"location":"models/#docforge.models.Module.get_object","title":"get_object","text":"
get_object(name: str) -> DocObject\n

Retrieve a documented object by name.

Parameters:

Name Type Description Default name str

Name of the object to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If no object with the given name exists.

"},{"location":"models/#docforge.models.Project","title":"Project","text":"
Project(name: str)\n

Representation of a documentation project.

A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

Attributes:

Name Type Description name str

Name of the project.

modules dict[str, Module]

Mapping of module paths to Module instances.

Initialize a Project instance.

Parameters:

Name Type Description Default name str

Name used to identify the documentation project.

required Example

Create a project and register a module:

```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
"},{"location":"models/#docforge.models.Project-functions","title":"Functions","text":""},{"location":"models/#docforge.models.Project.add_module","title":"add_module","text":"
add_module(module: Module) -> None\n

Register a module in the project.

Parameters:

Name Type Description Default module Module

Module instance to add to the project.

required"},{"location":"models/#docforge.models.Project.get_all_modules","title":"get_all_modules","text":"
get_all_modules() -> Iterable[Module]\n

Return all modules contained in the project.

Returns:

Type Description Iterable[Module]

Iterable[Module]: An iterable of Module instances.

"},{"location":"models/#docforge.models.Project.get_module","title":"get_module","text":"
get_module(path: str) -> Module\n

Retrieve a module by its dotted path.

Parameters:

Name Type Description Default path str

Fully qualified dotted module path (for example pkg.module).

required

Returns:

Name Type Description Module Module

The corresponding Module instance.

Raises:

Type Description KeyError

If the module does not exist in the project.

"},{"location":"models/#docforge.models.Project.get_module_list","title":"get_module_list","text":"
get_module_list() -> list[str]\n

Return the list of module import paths.

Returns:

Type Description list[str]

list[str]: A list containing the dotted paths of all modules in the project.

"},{"location":"models/module/","title":"Module","text":""},{"location":"models/module/#docforge.models.module","title":"docforge.models.module","text":""},{"location":"models/module/#docforge.models.module--summary","title":"Summary","text":"

Documentation model representing a Python module or package.

This module defines the Module class used in the doc-forge documentation model. A Module acts as a container for top-level documented objects (classes, functions, variables, and other members) discovered during introspection.

Notes "},{"location":"models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"models/module/#docforge.models.module.Module","title":"Module","text":"
Module(path: str, docstring: str | None = None)\n

Representation of a documented Python module or package.

A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

Attributes:

Name Type Description path str

Dotted import path of the module.

docstring str | None

Module-level documentation string, if present.

members dict[str, DocObject]

Mapping of object names to their corresponding DocObject representations.

Initialize a Module instance.

Parameters:

Name Type Description Default path str

Dotted import path identifying the module.

required docstring str | None

Module-level documentation text, if available.

None"},{"location":"models/module/#docforge.models.module.Module-functions","title":"Functions","text":""},{"location":"models/module/#docforge.models.module.Module.add_object","title":"add_object","text":"
add_object(obj: DocObject) -> None\n

Add a documented object to the module.

Parameters:

Name Type Description Default obj DocObject

Documentation object to register as a top-level member of the module.

required"},{"location":"models/module/#docforge.models.module.Module.get_all_objects","title":"get_all_objects","text":"
get_all_objects() -> Iterable[DocObject]\n

Return all top-level documentation objects in the module.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

"},{"location":"models/module/#docforge.models.module.Module.get_object","title":"get_object","text":"
get_object(name: str) -> DocObject\n

Retrieve a documented object by name.

Parameters:

Name Type Description Default name str

Name of the object to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If no object with the given name exists.

"},{"location":"models/object/","title":"Object","text":""},{"location":"models/object/#docforge.models.object","title":"docforge.models.object","text":""},{"location":"models/object/#docforge.models.object--summary","title":"Summary","text":"

Documentation model representing individual Python objects.

This module defines the DocObject class, the fundamental recursive unit of the doc-forge documentation model. Each DocObject represents a Python entity such as a class, function, method, or attribute, and may contain nested members that form a hierarchical documentation structure.

Notes "},{"location":"models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
DocObject(\n    name: str,\n    kind: str,\n    path: str,\n    signature: str | None = None,\n    docstring: str | None = None,\n)\n

Representation of a documented Python object.

A DocObject 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.

Attributes:

Name Type Description name str

Local name of the object.

kind str

Type of object (for example class, function, method, or attribute).

path str

Fully qualified dotted path to the object.

signature str | None

Callable signature if the object represents a callable.

docstring str | None

Raw docstring text extracted from the source code.

members dict[str, DocObject]

Mapping of member names to child DocObject instances.

Initialize a DocObject instance.

Parameters:

Name Type Description Default name str

Local name of the object.

required kind str

Object type identifier (for example class or function).

required path str

Fully qualified dotted path of the object.

required signature str | None

Callable signature if applicable.

None docstring str | None

Documentation string associated with the object.

None"},{"location":"models/object/#docforge.models.object.DocObject-functions","title":"Functions","text":""},{"location":"models/object/#docforge.models.object.DocObject.add_member","title":"add_member","text":"
add_member(obj: DocObject) -> None\n

Add a child documentation object.

This is typically used when attaching methods to classes or nested objects to their parent containers.

Parameters:

Name Type Description Default obj DocObject

Documentation object to add as a member.

required"},{"location":"models/object/#docforge.models.object.DocObject.get_all_members","title":"get_all_members","text":"
get_all_members() -> Iterable[DocObject]\n

Return all child members of the object.

Returns:

Type Description Iterable[DocObject]

Iterable[DocObject]: An iterable of DocObject instances representing nested members.

"},{"location":"models/object/#docforge.models.object.DocObject.get_member","title":"get_member","text":"
get_member(name: str) -> DocObject\n

Retrieve a member object by name.

Parameters:

Name Type Description Default name str

Name of the member to retrieve.

required

Returns:

Name Type Description DocObject DocObject

The corresponding DocObject instance.

Raises:

Type Description KeyError

If the member does not exist.

"},{"location":"models/project/","title":"Project","text":""},{"location":"models/project/#docforge.models.project","title":"docforge.models.project","text":""},{"location":"models/project/#docforge.models.project--summary","title":"Summary","text":"

Documentation model representing a project.

This module defines the Project class, the top-level container used by doc-forge to represent a documented codebase. A Project aggregates multiple modules and provides access to them through a unified interface.

Notes "},{"location":"models/project/#docforge.models.project-classes","title":"Classes","text":""},{"location":"models/project/#docforge.models.project.Project","title":"Project","text":"
Project(name: str)\n

Representation of a documentation project.

A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

Attributes:

Name Type Description name str

Name of the project.

modules dict[str, Module]

Mapping of module paths to Module instances.

Initialize a Project instance.

Parameters:

Name Type Description Default name str

Name used to identify the documentation project.

required Example

Create a project and register a module:

```python\nproject = Project(\"mypackage\")\nproject.add_module(module)\n```\n
"},{"location":"models/project/#docforge.models.project.Project-functions","title":"Functions","text":""},{"location":"models/project/#docforge.models.project.Project.add_module","title":"add_module","text":"
add_module(module: Module) -> None\n

Register a module in the project.

Parameters:

Name Type Description Default module Module

Module instance to add to the project.

required"},{"location":"models/project/#docforge.models.project.Project.get_all_modules","title":"get_all_modules","text":"
get_all_modules() -> Iterable[Module]\n

Return all modules contained in the project.

Returns:

Type Description Iterable[Module]

Iterable[Module]: An iterable of Module instances.

"},{"location":"models/project/#docforge.models.project.Project.get_module","title":"get_module","text":"
get_module(path: str) -> Module\n

Retrieve a module by its dotted path.

Parameters:

Name Type Description Default path str

Fully qualified dotted module path (for example pkg.module).

required

Returns:

Name Type Description Module Module

The corresponding Module instance.

Raises:

Type Description KeyError

If the module does not exist in the project.

"},{"location":"models/project/#docforge.models.project.Project.get_module_list","title":"get_module_list","text":"
get_module_list() -> list[str]\n

Return the list of module import paths.

Returns:

Type Description list[str]

list[str]: A list containing the dotted paths of all modules in the project.

"},{"location":"nav/","title":"Nav","text":""},{"location":"nav/#docforge.nav","title":"docforge.nav","text":"

Navigation layer for doc-forge.

The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.

"},{"location":"nav/#docforge.nav--workflow","title":"Workflow","text":"
  1. Specification \u2013 Users define navigation intent in docforge.nav.yml.
  2. Resolution \u2013 resolve_nav expands patterns and matches them against generated Markdown files.
  3. Emission \u2013 MkDocsNavEmitter converts the resolved structure into the YAML navigation format required by mkdocs.yml.

This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.

"},{"location":"nav/#docforge.nav-classes","title":"Classes","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

"},{"location":"nav/#docforge.nav.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.MkDocsNavEmitter.emit","title":"emit","text":"
emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

Generate a navigation structure for mkdocs.yml.

Parameters:

Name Type Description Default nav ResolvedNav

Resolved navigation data describing documentation groups and their associated Markdown files.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.

"},{"location":"nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

Parsed representation of a navigation specification.

A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page (for example index.md).

groups dict[str, list[str]]

Mapping of navigation group titles to lists of file patterns or glob expressions.

icon

Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home document.

required groups dict[str, list[str]]

Mapping of group names to lists of path patterns (glob expressions).

required icon dict[str, str] | None

Optional mapping of theme icon entries applied to the generated MkDocs configuration.

None"},{"location":"nav/#docforge.nav.NavSpec-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.NavSpec.all_patterns","title":"all_patterns","text":"
all_patterns() -> list[str]\n

Return all path patterns referenced by the specification.

Returns:

Type Description list[str]

list[str]: A list containing the home document (if defined) and all group pattern entries.

"},{"location":"nav/#docforge.nav.NavSpec.load","title":"load classmethod","text":"
load(path: Path) -> NavSpec\n

Load a navigation specification from a YAML file.

Parameters:

Name Type Description Default path Path

Filesystem path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed configuration.

Raises:

Type Description FileNotFoundError

If the specified file does not exist.

ValueError

If the file contents are not a valid navigation specification.

"},{"location":"nav/#docforge.nav.ResolvedNav","title":"ResolvedNav","text":"
ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page.

groups dict[str, list[Path]]

Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home page within the documentation root.

required groups dict[str, list[Path]]

Mapping of group titles to resolved documentation file paths.

required docs_root Path | None

Root directory of the documentation source files.

None"},{"location":"nav/#docforge.nav.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.ResolvedNav.all_files","title":"all_files","text":"
all_files() -> Iterable[Path]\n

Iterate over all files referenced by the navigation structure.

Yields:

Name Type Description Path Iterable[Path]

A documentation file referenced by the navigation, including the home page when defined.

Raises:

Type Description RuntimeError

If the home page is defined but the documentation root is not available for resolution.

"},{"location":"nav/#docforge.nav-functions","title":"Functions","text":""},{"location":"nav/#docforge.nav.build_wiki_nav","title":"build_wiki_nav","text":"
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

Derive an MkDocs navigation block from a wiki directory.

Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries compatible with the MkDocs nav configuration. The list is empty if the wiki contains no Markdown files.

Raises:

Type Description FileNotFoundError

If the wiki directory does not exist.

"},{"location":"nav/#docforge.nav.load_nav_spec","title":"load_nav_spec","text":"
load_nav_spec(path: Path) -> NavSpec\n

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

Parameters:

Name Type Description Default path Path

Path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed specification.

Raises:

Type Description FileNotFoundError

If the specification file does not exist.

ValueError

If the YAML structure is invalid.

"},{"location":"nav/#docforge.nav.resolve_nav","title":"resolve_nav","text":"
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name Type Description Default spec NavSpec

Navigation specification describing documentation layout.

required docs_root Path

Root directory containing documentation Markdown files.

required

Returns:

Name Type Description ResolvedNav ResolvedNav

A ResolvedNav instance containing validated navigation paths.

Raises:

Type Description FileNotFoundError

If the documentation root does not exist or a navigation pattern does not match any files.

"},{"location":"nav/mkdocs/","title":"Mkdocs","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs","title":"docforge.nav.mkdocs","text":"

MkDocs navigation emitter.

This module provides the MkDocsNavEmitter class, which converts a ResolvedNav instance into the navigation structure required by the MkDocs nav configuration.

Notes "},{"location":"nav/mkdocs/#docforge.nav.mkdocs-classes","title":"Classes","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter","title":"MkDocsNavEmitter","text":"

Emit MkDocs navigation structures from resolved navigation data.

The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.

"},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter-functions","title":"Functions","text":""},{"location":"nav/mkdocs/#docforge.nav.mkdocs.MkDocsNavEmitter.emit","title":"emit","text":"
emit(nav: ResolvedNav) -> list[dict[str, Any]]\n

Generate a navigation structure for mkdocs.yml.

Parameters:

Name Type Description Default nav ResolvedNav

Resolved navigation data describing documentation groups and their associated Markdown files.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: A list of dictionaries representing the MkDocs navigation layout. Each dictionary maps a navigation label to a page or a list of pages.

"},{"location":"nav/resolver/","title":"Resolver","text":""},{"location":"nav/resolver/#docforge.nav.resolver","title":"docforge.nav.resolver","text":"

Navigation resolution utilities.

This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.

Notes "},{"location":"nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
ResolvedNav(\n    home: str | None,\n    groups: dict[str, list[Path]],\n    docs_root: Path | None = None,\n)\n

Resolved navigation structure.

A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page.

groups dict[str, list[Path]]

Mapping of navigation group titles to lists of resolved documentation file paths.

Initialize a ResolvedNav instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home page within the documentation root.

required groups dict[str, list[Path]]

Mapping of group titles to resolved documentation file paths.

required docs_root Path | None

Root directory of the documentation source files.

None"},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav.all_files","title":"all_files","text":"
all_files() -> Iterable[Path]\n

Iterate over all files referenced by the navigation structure.

Yields:

Name Type Description Path Iterable[Path]

A documentation file referenced by the navigation, including the home page when defined.

Raises:

Type Description RuntimeError

If the home page is defined but the documentation root is not available for resolution.

"},{"location":"nav/resolver/#docforge.nav.resolver-functions","title":"Functions","text":""},{"location":"nav/resolver/#docforge.nav.resolver.resolve_nav","title":"resolve_nav","text":"
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n

Resolve a navigation specification against the filesystem.

The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.

Parameters:

Name Type Description Default spec NavSpec

Navigation specification describing documentation layout.

required docs_root Path

Root directory containing documentation Markdown files.

required

Returns:

Name Type Description ResolvedNav ResolvedNav

A ResolvedNav instance containing validated navigation paths.

Raises:

Type Description FileNotFoundError

If the documentation root does not exist or a navigation pattern does not match any files.

"},{"location":"nav/spec/","title":"Spec","text":""},{"location":"nav/spec/#docforge.nav.spec","title":"docforge.nav.spec","text":"

Navigation specification model.

This module defines the NavSpec class, which represents the navigation structure defined by the user in the doc-forge navigation specification (typically docforge.nav.yml).

Notes "},{"location":"nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
NavSpec(\n    home: str | None,\n    groups: dict[str, list[str]],\n    icon: dict[str, str] | None = None,\n)\n

Parsed representation of a navigation specification.

A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.

Attributes:

Name Type Description home str | None

Relative path to the documentation home page (for example index.md).

groups dict[str, list[str]]

Mapping of navigation group titles to lists of file patterns or glob expressions.

icon

Optional mapping of theme icon entries (for example {\"logo\": \"material/code-tags\"}) injected into the MkDocs theme as theme.icon.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home str | None

Relative path to the home document.

required groups dict[str, list[str]]

Mapping of group names to lists of path patterns (glob expressions).

required icon dict[str, str] | None

Optional mapping of theme icon entries applied to the generated MkDocs configuration.

None"},{"location":"nav/spec/#docforge.nav.spec.NavSpec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec.all_patterns","title":"all_patterns","text":"
all_patterns() -> list[str]\n

Return all path patterns referenced by the specification.

Returns:

Type Description list[str]

list[str]: A list containing the home document (if defined) and all group pattern entries.

"},{"location":"nav/spec/#docforge.nav.spec.NavSpec.load","title":"load classmethod","text":"
load(path: Path) -> NavSpec\n

Load a navigation specification from a YAML file.

Parameters:

Name Type Description Default path Path

Filesystem path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed configuration.

Raises:

Type Description FileNotFoundError

If the specified file does not exist.

ValueError

If the file contents are not a valid navigation specification.

"},{"location":"nav/spec/#docforge.nav.spec-functions","title":"Functions","text":""},{"location":"nav/spec/#docforge.nav.spec.load_nav_spec","title":"load_nav_spec","text":"
load_nav_spec(path: Path) -> NavSpec\n

Load a navigation specification file.

This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.

Parameters:

Name Type Description Default path Path

Path to the navigation specification file.

required

Returns:

Name Type Description NavSpec NavSpec

A NavSpec instance representing the parsed specification.

Raises:

Type Description FileNotFoundError

If the specification file does not exist.

ValueError

If the YAML structure is invalid.

"},{"location":"nav/wiki/","title":"Wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki","title":"docforge.nav.wiki","text":""},{"location":"nav/wiki/#docforge.nav.wiki--summary","title":"Summary","text":"

Wiki navigation derivation.

This module provides build_wiki_nav, which derives an MkDocs-ready navigation block from the file structure of a hand-written wiki directory (typically docs/wiki). wiki content is authored by hand and is never modified by doc-forge; only the navigation layout is inferred.

"},{"location":"nav/wiki/#docforge.nav.wiki--notes","title":"Notes","text":""},{"location":"nav/wiki/#docforge.nav.wiki-functions","title":"Functions","text":""},{"location":"nav/wiki/#docforge.nav.wiki.build_wiki_nav","title":"build_wiki_nav","text":"
build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]\n

Derive an MkDocs navigation block from a wiki directory.

Returned paths are relative to the parent of wiki_dir and carry the wiki directory name as their leading component (for example wiki/01_overview.md when the wiki lives at docs/wiki). This makes the result directly usable in an MkDocs nav block with

Parameters:

Name Type Description Default wiki_dir Path

Path to the hand-written wiki directory, for example docs/wiki.

required

Returns:

Type Description list[dict[str, Any]]

list[dict[str, Any]]: Navigation entries compatible with the MkDocs nav configuration. The list is empty if the wiki contains no Markdown files.

Raises:

Type Description FileNotFoundError

If the wiki directory does not exist.

"},{"location":"renderers/","title":"Renderers","text":""},{"location":"renderers/#docforge.renderers","title":"docforge.renderers","text":""},{"location":"renderers/#docforge.renderers--summary","title":"Summary","text":"

Renderers layer for doc-forge.

The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.

"},{"location":"renderers/#docforge.renderers--overview","title":"Overview","text":"

Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

Current implementations:

"},{"location":"renderers/#docforge.renderers--extending","title":"Extending","text":"

New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.

"},{"location":"renderers/#docforge.renderers-classes","title":"Classes","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"renderers/#docforge.renderers.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"renderers/#docforge.renderers.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"renderers/#docforge.renderers.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"renderers/#docforge.renderers.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"renderers/base/","title":"Base","text":""},{"location":"renderers/base/#docforge.renderers.base","title":"docforge.renderers.base","text":""},{"location":"renderers/base/#docforge.renderers.base--summary","title":"Summary","text":"

Renderer base interfaces and configuration models.

This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.

"},{"location":"renderers/base/#docforge.renderers.base-classes","title":"Classes","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer","title":"DocRenderer","text":"

Bases: Protocol

Protocol defining the interface for documentation renderers.

Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.

"},{"location":"renderers/base/#docforge.renderers.base.DocRenderer-functions","title":"Functions","text":""},{"location":"renderers/base/#docforge.renderers.base.DocRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate renderer-specific documentation sources.

Parameters:

Name Type Description Default project Project

Project model containing modules and documentation objects.

required out_dir Path

Directory where generated documentation sources should be written.

required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig","title":"RendererConfig","text":"
RendererConfig(out_dir: Path, project: Project)\n

Configuration container for documentation renderers.

A RendererConfig instance groups together the project model and the output directory used during rendering.

Attributes:

Name Type Description out_dir Path

Directory where generated documentation files will be written.

project Project

Documentation project model to be rendered.

Initialize a RendererConfig instance.

Parameters:

Name Type Description Default out_dir Path

Target directory where documentation files should be written.

required project Project

Introspected project model to render.

required"},{"location":"renderers/base/#docforge.renderers.base.RendererConfig-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/","title":"Mcp Renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer","title":"docforge.renderers.mcp_renderer","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer--summary","title":"Summary","text":"

MCP renderer implementation.

This module defines the MCPRenderer class, which generates documentation resources compatible with the Model Context Protocol (MCP).

"},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer-classes","title":"Classes","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer","title":"MCPRenderer","text":"

Renderer that generates MCP-compatible documentation resources.

This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).

"},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer-functions","title":"Functions","text":""},{"location":"renderers/mcp_renderer/#docforge.renderers.mcp_renderer.MCPRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path) -> None\n

Generate MCP documentation resources for a project.

The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.

Parameters:

Name Type Description Default project Project

Documentation project model to render.

required out_dir Path

Directory where MCP resources will be written.

required"},{"location":"renderers/mkdocs_renderer/","title":"Mkdocs Renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer","title":"docforge.renderers.mkdocs_renderer","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer--summary","title":"Summary","text":"

MkDocs renderer implementation.

This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

The renderer ensures a consistent documentation structure by:

"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer-classes","title":"Classes","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer","title":"MkDocsRenderer","text":"

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer-functions","title":"Functions","text":""},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme","title":"generate_readme","text":"
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

Generate a README.md file from the root module docstring.

Notes

Parameters:

Name Type Description Default project Project

Project model containing documentation metadata.

required docs_dir Path

Directory containing generated documentation sources.

required module_is_source bool | None

Whether the module is treated as the project source root.

None readme_dir Path | None

Directory where the generated README.md should be written. Defaults to the parent of docs_dir.

None"},{"location":"renderers/mkdocs_renderer/#docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(\n    project: Project,\n    out_dir: Path,\n    module_is_source: bool | None = None,\n) -> None\n

Generate Markdown documentation files for a project.

This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.

Parameters:

Name Type Description Default project Project

Project model containing modules to document.

required out_dir Path

Directory where generated Markdown files will be written.

required module_is_source bool | None

If True, treat the specified module as the documentation root rather than nesting it inside a folder.

None"},{"location":"servers/","title":"Servers","text":""},{"location":"servers/#docforge.servers","title":"docforge.servers","text":""},{"location":"servers/#docforge.servers--summary","title":"Summary","text":"

Server layer for doc-forge.

This module exposes server implementations used to provide live access to generated documentation resources. Currently, it includes the MCP documentation server.

"},{"location":"servers/#docforge.servers-classes","title":"Classes","text":""},{"location":"servers/#docforge.servers.MCPServer","title":"MCPServer","text":"
MCPServer(mcp_root: Path, name: str)\n

MCP server for serving a pre-generated documentation bundle.

The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

Attributes:

Name Type Description mcp_root Path

Directory containing the generated MCP documentation bundle.

app FastMCP

Underlying FastMCP application instance that registers resources and tools.

Initialize the MCP server.

Parameters:

Name Type Description Default mcp_root Path

Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

required name str

Identifier used for the MCP server instance.

required"},{"location":"servers/#docforge.servers.MCPServer-functions","title":"Functions","text":""},{"location":"servers/#docforge.servers.MCPServer.run","title":"run","text":"
run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

Start the MCP server.

Parameters:

Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

'streamable-http'"},{"location":"servers/mcp_server/","title":"Mcp Server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server","title":"docforge.servers.mcp_server","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server--summary","title":"Summary","text":"

MCP server implementation.

This module defines the MCPServer class, which serves pre-generated documentation bundles through the Model Context Protocol (MCP).

Notes "},{"location":"servers/mcp_server/#docforge.servers.mcp_server-classes","title":"Classes","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer","title":"MCPServer","text":"
MCPServer(mcp_root: Path, name: str)\n

MCP server for serving a pre-generated documentation bundle.

The server exposes documentation resources and diagnostic tools through MCP endpoints backed by JSON files generated by the MCP renderer.

Attributes:

Name Type Description mcp_root Path

Directory containing the generated MCP documentation bundle.

app FastMCP

Underlying FastMCP application instance that registers resources and tools.

Initialize the MCP server.

Parameters:

Name Type Description Default mcp_root Path

Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).

required name str

Identifier used for the MCP server instance.

required"},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer-functions","title":"Functions","text":""},{"location":"servers/mcp_server/#docforge.servers.mcp_server.MCPServer.run","title":"run","text":"
run(\n    transport: Literal[\n        \"stdio\", \"sse\", \"streamable-http\"\n    ] = \"streamable-http\",\n) -> None\n

Start the MCP server.

Parameters:

Name Type Description Default transport Literal['stdio', 'sse', 'streamable-http']

Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.

'streamable-http'"}]}