{"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":""},{"location":"#docforge--generate-an-mkdocs-site-from-a-python-package","title":"Generate an MkDocs site from a Python package:","text":"
doc-forge build --mkdocs --module 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--generate-mkdocs-site-and-mcp-json-documentation","title":"Generate MkDocs site and MCP JSON documentation:","text":"
doc-forge build --mcp --mkdocs --module my_package\n
"},{"location":"#docforge--serve-mkdocs-locally","title":"Serve MkDocs locally:","text":"
doc-forge serve --mkdocs --module my_package\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 structured sections.

"},{"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.

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.

"},{"location":"#docforge.GriffeLoader.load_project","title":"load_project","text":"
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> 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

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

None skip_import_errors bool

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(project: Project, docs_dir: Path, module_is_source: bool | None = None) -> None\n

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

Behavior:

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

Whether the module is treated as the project source root.

None"},{"location":"#docforge.MkDocsRenderer.generate_sources","title":"generate_sources","text":"
generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> 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

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(module_name: str, project_root: Path | None = None) -> 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

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

"},{"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(mcp: bool, mkdocs: bool, module_is_source: bool, module: Optional[str], project_name: Optional[str], site_name: Optional[str], docs_dir: Path, nav_file: Path, template: Optional[Path], mkdocs_yml: Path, out_dir: Path) -> None\n

Build documentation artifacts.

This command performs the full documentation build pipeline:

  1. Introspects the Python project using Griffe
  2. Generates renderer-specific documentation sources
  3. Optionally builds the final documentation output

Depending on the selected options, the build can target:

Parameters:

Name Type Description Default mcp bool

Enable MCP documentation generation.

required mkdocs bool

Enable MkDocs documentation generation.

required module_is_source bool

Treat the specified module directory as the project root.

required module Optional[str]

Python module import path to document.

required project_name Optional[str]

Optional override for the project name.

required site_name Optional[str]

Display name for the MkDocs site.

required docs_dir Path

Directory where Markdown documentation sources will be generated.

required nav_file Path

Path to the navigation specification file.

required template Optional[Path]

Optional custom MkDocs configuration template.

required mkdocs_yml Path

Output path for the generated MkDocs configuration.

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(mcp: bool, mkdocs: bool, module: Optional[str], mkdocs_yml: Path, out_dir: Path) -> None\n

Serve generated documentation locally.

Depending on the selected mode, this command starts either:

Parameters:

Name Type Description Default mcp bool

Serve documentation using the MCP server.

required mkdocs bool

Serve the MkDocs development site.

required module Optional[str]

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: Optional[str]) -> 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 Optional[str]

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.

"},{"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(module: str, project_name: str | None, out_dir: Path) -> 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 Optional[str]

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.

"},{"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","title":"build","text":"
build(mkdocs_yml: Path) -> None\n

Build the MkDocs documentation site.

This function loads the MkDocs configuration and runs the MkDocs build command to generate the final static documentation site.

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":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_config","title":"generate_config","text":"
generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None\n

Generate an mkdocs.yml configuration file.

The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation specification.

Parameters:

Name Type Description Default docs_dir Path

Directory containing generated documentation Markdown files.

required nav_file Path

Path to the docforge.nav.yml navigation specification.

required template Optional[Path]

Optional path to a custom MkDocs configuration template. If not provided, a built-in template will be used.

required out Path

Destination path where the generated mkdocs.yml file will be written.

required site_name str

Display name for the generated documentation site.

required

Raises:

Type Description FileError

If the navigation specification or template file cannot be found.

"},{"location":"cli/mkdocs_utils/#docforge.cli.mkdocs_utils.generate_sources","title":"generate_sources","text":"
generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None) -> 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 Optional[str]

Optional override for the project name used in documentation metadata.

None module_is_source Optional[bool]

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

None"},{"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":"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.

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.

"},{"location":"loaders/#docforge.loaders.GriffeLoader.load_project","title":"load_project","text":"
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> 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

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

None skip_import_errors bool

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(module_name: str, project_root: Path | None = None) -> 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

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.

"},{"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.

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.

"},{"location":"loaders/griffe_loader/#docforge.loaders.griffe_loader.GriffeLoader.load_project","title":"load_project","text":"
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> 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

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

None skip_import_errors bool

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(module_name: str, project_root: Path | None = None) -> 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

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(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None)\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 Optional[str]

Callable signature if the object represents a callable.

docstring Optional[str]

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 Optional[str]

Callable signature if applicable.

None docstring Optional[str]

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: Optional[str] = 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 Optional[str]

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 Optional[str]

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"},{"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.

"},{"location":"models/module/#docforge.models.module-classes","title":"Classes","text":""},{"location":"models/module/#docforge.models.module.Module","title":"Module","text":"
Module(path: str, docstring: Optional[str] = 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 Optional[str]

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 Optional[str]

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.

"},{"location":"models/object/#docforge.models.object-classes","title":"Classes","text":""},{"location":"models/object/#docforge.models.object.DocObject","title":"DocObject","text":"
DocObject(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None)\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 Optional[str]

Callable signature if the object represents a callable.

docstring Optional[str]

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 Optional[str]

Callable signature if applicable.

None docstring Optional[str]

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.

"},{"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"},{"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]]

A list of dictionaries representing the MkDocs navigation layout.

List[Dict[str, Any]]

Each dictionary maps a navigation label to a page or a list of

List[Dict[str, Any]]

pages.

"},{"location":"nav/#docforge.nav.NavSpec","title":"NavSpec","text":"
NavSpec(home: Optional[str], groups: Dict[str, List[str]])\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 Optional[str]

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.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home Optional[str]

Relative path to the home document.

required groups Dict[str, List[str]]

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

required"},{"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]

A list containing the home document (if defined) and all

List[str]

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:

Type Description 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(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None)\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 Optional[str]

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.

Returns:

Type Description Iterable[Path]

An iterable of Path objects representing documentation files.

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

Type Description 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:

Type Description 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.

"},{"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]]

A list of dictionaries representing the MkDocs navigation layout.

List[Dict[str, Any]]

Each dictionary maps a navigation label to a page or a list of

List[Dict[str, Any]]

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.

"},{"location":"nav/resolver/#docforge.nav.resolver-classes","title":"Classes","text":""},{"location":"nav/resolver/#docforge.nav.resolver.ResolvedNav","title":"ResolvedNav","text":"
ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None)\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 Optional[str]

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.

Returns:

Type Description Iterable[Path]

An iterable of Path objects representing documentation files.

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:

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

"},{"location":"nav/spec/#docforge.nav.spec-classes","title":"Classes","text":""},{"location":"nav/spec/#docforge.nav.spec.NavSpec","title":"NavSpec","text":"
NavSpec(home: Optional[str], groups: Dict[str, List[str]])\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 Optional[str]

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.

Initialize a NavSpec instance.

Parameters:

Name Type Description Default home Optional[str]

Relative path to the home document.

required groups Dict[str, List[str]]

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

required"},{"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]

A list containing the home document (if defined) and all

List[str]

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:

Type Description 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:

Type Description 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":"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(project: Project, docs_dir: Path, module_is_source: bool | None = None) -> None\n

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

Behavior:

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

Whether the module is treated as the project source root.

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

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(project: Project, docs_dir: Path, module_is_source: bool | None = None) -> None\n

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

Behavior:

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

Whether the module is treated as the project source root.

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

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.

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(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> 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).

"},{"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.

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(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> 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'"}]}