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 -
1
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 +
Build documentation (MkDocs site or MCP resources).
This command orchestrates the full build process: -1. Introspects the code (Griffe) -2. Renders sources (MkDocs Markdown or MCP JSON) -3. (MkDocs only) Generates config and runs the final site build.
Build documentation artifacts.
This command performs the full documentation build pipeline:
Depending on the selected options, the build can target:
Parameters:
Use the MCP documentation builder.
Enable MCP documentation generation.
Use the MkDocs documentation builder.
Enable MkDocs documentation generation.
Module is the source folder and to be treated as the root folder.
Treat the specified module directory as the +project root.
The dotted path of the module to the document.
Python module import path to document.
(MkDocs) The site display name. Defaults to module name.
Display name for the MkDocs site.
(MkDocs) Target directory for Markdown sources.
Directory where Markdown documentation sources +will be generated.
(MkDocs) Path to the docforge.nav.yml specification.
Path to the navigation specification file.
(MkDocs) Optional custom mkdocs.yml template.
Optional custom MkDocs configuration template.
(MkDocs) Target path for the generated mkdocs.yml.
Output path for the generated MkDocs configuration.
(MCP) Target directory for MCP JSON resources.
Output directory for generated MCP resources.
Raises:
UsageError
If required options are missing or conflicting.
serve(mcp: bool, mkdocs: bool, module: Optional[str], mkdocs_yml: Path, out_dir: Path) -> None -
serve(mcp: bool, mkdocs: bool, module: Optional[str], mkdocs_yml: Path, out_dir: Path) -> None +
Serve documentation (MkDocs or MCP).
Serve generated documentation locally.
Depending on the selected mode, this command starts either:
Serve MCP resources via an MCP server.
Serve documentation using the MCP server.
Serve the MkDocs site using the built-in development server.
Serve the MkDocs development site.
The dotted path of the module to serve.
Python module import path to serve via MCP.
(MkDocs) Path to the mkdocs.yml configuration.
Path to the MkDocs configuration file.
(MCP) Path to the mcp_docs/ directory.
Root directory containing MCP documentation resources.
If invalid or conflicting options are provided.
tree(module: str, project_name: Optional[str]) -> None -
tree(module: str, project_name: Optional[str]) -> None +
Visualize the project structure in the terminal.
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.
The module import path to recursively introspect.
Python module import path to introspect.
Optional override for the project name shown at the root.
Optional name to display as the project root.
The docforge.cli package provides the command-line interface for interacting -with doc-forge.
docforge.cli
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.
doc-forge
docforge.cli.main
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.
The CLI is normally invoked through the installed command:
doc-forge <command> [options] +
Programmatic invocation is also possible:
1 +2
from docforge.cli import main +main() +
Main entry point for the doc-forge CLI. This module delegates all command -execution to docforge.cli.commands.
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.
docforge.cli.commands
main() -> None -
main() -> None +
CLI Entry point. Boots the click application.
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.
generate_resources(module: str, project_name: str | None, out_dir: Path) -> None -
generate_resources(module: str, project_name: str | None, out_dir: Path) -> None +
Generate MCP-compatible documentation resources.
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.
The dotted path of the primary module to document.
Python module import path used as the entry point for +documentation generation.
Optional override for the project name.
Optional override for the project name used in +generated documentation metadata.
Directory where the MCP JSON resources and nav will be written.
Directory where MCP resources (index.json, nav.json, +and module data) will be written.
serve(module: str, mcp_root: Path) -> None -
serve(module: str, mcp_root: Path) -> None +
Serve MCP documentation from a pre-built bundle.
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.
The dotted path of the primary module to serve.
Python module import path used to identify the served +documentation instance.
Path to the directory containing index.json, nav.json, and modules/.
Path to the directory containing the MCP documentation +bundle (index.json, nav.json, and modules/).
ClickException
If the MCP documentation bundle is missing +required files or directories.
build(mkdocs_yml: Path) -> None -
build(mkdocs_yml: Path) -> None +
Build the documentation site using MkDocs.
Build the MkDocs documentation site.
This function loads the MkDocs configuration and runs the MkDocs +build command to generate the final static documentation site.
Path to the mkdocs.yml configuration file.
mkdocs.yml
If the configuration file does not exist.
generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None -
generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None +
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.
Path to the directory containing documentation Markdown files.
Directory containing generated documentation Markdown files.
Path to the docforge.nav.yml specification.
Path to the docforge.nav.yml navigation specification.
docforge.nav.yml
Optional path to an mkdocs.yml template (overrides built-in).
Optional path to a custom MkDocs configuration template. +If not provided, a built-in template will be used.
Path where the final mkdocs.yml will be written.
Destination path where the generated mkdocs.yml file +will be written.
The display name for the documentation site.
Display name for the generated documentation site.
FileError
If the navigation specification or template +file cannot be found.
generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None) -> None -
generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None) -> None +
Generate Markdown source files for the specified module.
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.
project_name
str | None
None
docs_dir
Optional override for the project name used in +documentation metadata.
module_is_source
If True, treat the specified module directory as +the project root rather than a nested module.
serve(mkdocs_yml: Path) -> None -
serve(mkdocs_yml: Path) -> None +
Serve the documentation site with live-reload using MkDocs.
Start an MkDocs development server with live reload.
The server watches documentation files and automatically reloads +the site when changes are detected.
doc-forge is a renderer-agnostic Python documentation compiler designed for -speed, flexibility, and beautiful output. It decouples the introspection of -your code from the rendering process, allowing you to generate documentation -for various platforms (starting with MkDocs) from a single internal models.
doc-forge operates on two fundamental principles:
mypackage.utils
doc-forge is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
__init__.py
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.
Install using pip with the optional mkdocs dependencies for a complete setup:
pip
mkdocs
pip install doc-forge -
Build Documentation: - Introspect your package and generate documentation in one step: - ```bash - # Build MkDocs site - doc-forge build --mkdocs --module my_package --site-name "My Docs"
doc-forge build --mcp --module my_package -```
Define Navigation: - Create a docforge.nav.yml to organize your documentation: - yaml - home: my_package/index.md - groups: - Core API: - - my_package/core/*.md - Utilities: - - my_package/utils.md
yaml - home: my_package/index.md - groups: - Core API: - - my_package/core/*.md - Utilities: - - my_package/utils.md
Preview: - ```bash - # Serve MkDocs site - doc-forge serve --mkdocs
doc-forge serve --mcp -```
Install using pip:
pip install doc-forge +
Generate a MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package +
Generate MCP JSON documentation:
doc-forge build --mcp --module my_package +
Serve documentation locally:
doc-forge serve --mkdocs --module my_package +
Loader
Extracts symbols, signatures, and docstrings using static analysis.
Semantic model
Structured, renderer-agnostic representation of the API.
Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON.
Symbol
Any documentable object:
1 +2 +3 +4 +5 +6
- module +- class +- function +- method +- property +- attribute +
doc-forge follows a compiler architecture:
Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings. +
Middle-end:
Builds a semantic model describing symbols and relationships. +
Back-end:
Renders documentation using interchangeable renderers. +
This architecture ensures deterministic documentation generation.
Typical flow:
1 +2 +3 +4 +5 +6 +7 +8 +9
Python package + ↓ +Loader (static analysis) + ↓ +Semantic model + ↓ +Renderer + ↓ +MkDocs site or MCP JSON +
Build MkDocs documentation:
Build MCP documentation:
Serve MkDocs locally:
doc-forge serve --module my_package +
Loaders:
GriffeLoader +discover_module_paths +
Renderers:
MkDocsRenderer +MCPRenderer +
CLI:
main +
Models:
models +
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
docforge.loaders
griffe
docforge.models
docforge.renderers
docforge.nav
---
Recommended sections:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10
## Summary +## Installation +## Quick start +## Core concepts +## Architecture +## Rendering pipeline +## CLI usage +## Public API +## Examples +## Notes +
Package Doc String:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32
''' +Foo-bar processing framework. + +Provides tools for defining Foo objects and executing Bar pipelines. + +--- + +# Installation + + pip install foo-bar + +--- + +# Quick start + + from foobar import Foo, BarEngine + + foo = Foo("example") + engine = BarEngine([foo]) + + result = engine.run() + +--- + +# Public API + + Foo + Bar + BarEngine + +--- +''' +
1 +2 +3 +4
## Summary +## Examples +## Notes +## Public API +
Module Doc String:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19
''' +Foo execution subsystem. + +Provides utilities for executing Foo objects through Bar stages. + +--- + +Example: + + from foobar.engine import BarEngine + from foobar.foo import Foo + + foo = Foo("example") + + engine = BarEngine([foo]) + engine.run() + +--- +''' +
Attributes: +Notes: +Example: +Raises: +
Simple Foo:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27
class Foo: + ''' + Represents a unit of work. + + Attributes: + name (str): + Identifier of the foo instance. + + value (int): + Numeric value associated with foo. + + Notes: + Guarantees: + + - instances are immutable after creation + + Lifecycle: + + - create instance + - pass to processing engine + + Example: + Create and inspect a Foo: + + foo = Foo("example", value=42) + print(foo.name) + ''' +
Complex Bar:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22
class BarEngine: + ''' + Executes Foo objects through Bar stages. + + Attributes: + foos (tuple[Foo, ...]): + Foo instances managed by the engine. + + Notes: + Guarantees: + + - deterministic execution order + + Example: + Run engine: + + foo1 = Foo("a") + foo2 = Foo("b") + + engine = BarEngine([foo1, foo2]) + engine.run() + ''' +
Args: +Returns: +Raises: +Yields: +Notes: +Example: +
Simple process method:
def process(foo: Foo, multiplier: int) -> int: + ''' + Process a Foo instance. + + Args: + foo (Foo): + Foo instance to process. + + multiplier (int): + Value used to scale foo. + + Returns: + int: + Processed result. + + Raises: + ValueError: + If multiplier is negative. + + Notes: + Guarantees: + + - foo is not modified + + Example: + Process foo: + + foo = Foo("example", value=10) + + result = process(foo, multiplier=2) + print(result) + ''' +
Multiple Examples:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28
def combine(foo_a: Foo, foo_b: Foo) -> Foo: + ''' + Combine two Foo instances. + + Args: + foo_a (Foo): + First foo. + + foo_b (Foo): + Second foo. + + Returns: + Foo: + Combined foo. + + Example: + Basic usage: + + foo1 = Foo("a") + foo2 = Foo("b") + + combined = combine(foo1, foo2) + + Pipeline usage: + + engine = BarEngine([foo1, foo2]) + engine.run() + ''' +
Property Doc String:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14
@property +def foos(self) -> tuple[Foo, ...]: + ''' + Return contained Foo instances. + + Returns: + tuple[Foo, ...]: + Stored foo objects. + + Example: + container = FooContainer() + + foos = container.foos + ''' +
Attribute Doc String:
''' +Represents a processing stage. + +Attributes: + id (str): + Unique identifier. + + enabled (bool): + Whether the stage is active. +''' +
Notes Example:
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13
Notes: + **Guarantees:** + + - deterministic behavior + + **Lifecycle:** + + - created during initialization + - reused across executions + + **Thread safety:** + + - safe for concurrent reads +
Single example:
Example: + + foo = Foo("example") + process(foo, multiplier=2) +
Multiple examples:
Example: + Create foo: + + foo = Foo("example") + + Run engine: + + engine = BarEngine([foo]) + engine.run() +
Avoid fenced code blocks inside structured sections.
Use horizontal separators only at docstring root level to separate sections:
--- +
Allowed locations:
Do not use separators inside code sections.
GSDFC ensures doc-forge can deterministically extract:
This enables:
GriffeLoader() -
GriffeLoader() +
Loads Python modules and extracts documentation using the Griffe introspection engine.
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.
Project
Module
DocObject
Initialize the GriffeLoader.
Initialize the Griffe-backed loader.
Creates an internal Griffe loader instance with dedicated collections +for modules and source lines.
load_module(path: str) -> Module -
load_module(path: str) -> Module +
Load a single module and convert its introspection data into the docforge models.
Load and convert a single Python module.
The module is introspected using Griffe and then transformed into +a doc-forge Module model.
The dotted path of the module to load.
Dotted import path of the module.
A Module instance.
A populated Module instance.
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> Project -
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> Project +
Load multiple modules and combine them into a single Project models.
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.
A list of dotted paths to the modules to load.
List of dotted module import paths to load.
Optional name for the project. Defaults to the first module name.
Optional override for the project name. Defaults +to the top-level name of the first module.
If True, modules that fail to import will be skipped.
If True, modules that fail to load will be +skipped instead of raising an error.
A Project instance containing the loaded modules.
A populated Project instance containing the loaded modules.
ValueError
If no module paths are provided.
ImportError
If a module fails to load and +skip_import_errors is False.
skip_import_errors
Renderer that emits MCP-native JSON resources from docforge models.
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).
generate_sources(project: Project, out_dir: Path) -> None -
generate_sources(project: Project, out_dir: Path) -> None +
Generate MCP-compatible JSON resources and navigation for the project.
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.
nav.json
index.json
The project model to render.
Documentation project model to render.
Target directory for the generated JSON files.
Directory where MCP resources will be written.
Renderer that generates Markdown source files formatted for the MkDocs -'mkdocstrings' plugin.
Renderer that produces Markdown documentation for MkDocs.
Generated pages use mkdocstrings directives to reference Python modules, +allowing MkDocs to render API documentation dynamically.
generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None -
generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None) -> None +
Produce a set of Markdown files in the output directory based on the -provided Project models.
Generate a README.md file from the root module docstring.
README.md
Behavior:
The project models to render.
Project model containing documentation metadata.
out_dir
Path
Target directory for documentation files.
Directory containing generated documentation sources.
Whether the module is treated as the project +source root.
generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None +
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.
project
Project model containing modules to document.
Directory where generated Markdown files will be written.
bool | None
If True, treat the specified module as the +documentation root rather than nesting it inside a folder.
discover_module_paths(module_name: str, project_root: Path | None = None) -> List[str] -
discover_module_paths(module_name: str, project_root: Path | None = None) -> List[str] +
Discover all Python modules under a package via filesystem traversal.
Rules: -- Directory with init.py is treated as a package. -- Any .py file is treated as a module. -- All paths are converted to dotted module paths.
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.
.py
Discovery rules:
The name of the package to discover.
Top-level package name to discover modules from.
The root directory of the project. Defaults to current working directory.
Root directory used to resolve module paths. If not +provided, the current working directory is used.
A sorted list of dotted module paths.
A sorted list of unique dotted module import paths.
FileNotFoundError
If the specified package directory does not exist.
This module provides the GriffeLoader, which uses the 'griffe' library to -introspect Python source code and populate the doc-forge Project models.
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.
GriffeLoader
The docforge.loaders package is responsible for discovering Python source files -and extracting their documentation using static analysis.
Loader layer for doc-forge.
The docforge.loaders package is responsible for discovering Python modules +and extracting documentation data using static analysis.
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:
_
The docforge.models package provides the core data structures used to represent -Python source code in a documentation-focused hierarchy.
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.
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 classes are designed to be renderer-agnostic, allowing the same internal -representation to be transformed into various output formats (currently MkDocs).
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).
DocObject(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None) -
DocObject(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None) +
Represents a documented Python object (class, function, method, etc.).
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:
Type of object (e.g., 'class', 'function', 'attribute').
Type of object (for example class, function, +method, or attribute).
class
function
method
attribute
Full dotted import path to the object.
Fully qualified dotted path to the object.
Callable signature, if applicable.
Callable signature if the object represents a callable.
Raw docstring content extracted from the source.
Raw docstring text extracted from the source code.
Dictionary mapping member names to their DocObject representations.
Mapping of member names to child DocObject instances.
Initialize a new DocObject.
Initialize a DocObject instance.
The local name of the object.
Local name of the object.
The kind of object (e.g., 'class', 'function').
Object type identifier (for example class or function).
The full dotted path to the object.
Fully qualified dotted path of the object.
The object's signature (for callable objects).
Callable signature if applicable.
The object's docstring, if any.
Documentation string associated with the object.
add_member(obj: DocObject) -> None -
add_member(obj: DocObject) -> None +
Add a child member to this object (e.g., a method to a class).
Add a child documentation object.
This is typically used when attaching methods to classes or +nested objects to their parent containers.
The child DocObject to add.
Documentation object to add as a member.
get_all_members() -> Iterable[DocObject] -
get_all_members() -> Iterable[DocObject] +
Get all members of this object.
Return all child members of the object.
Returns:
An iterable of child DocObject instances.
An iterable of DocObject instances representing nested members.
get_member(name: str) -> DocObject -
get_member(name: str) -> DocObject +
Retrieve a child member by name.
Retrieve a member object by name.
The name of the member.
Name of the member to retrieve.
The requested DocObject.
The corresponding DocObject instance.
KeyError
If the member does not exist.
Module(path: str, docstring: Optional[str] = None) -
Module(path: str, docstring: Optional[str] = None) +
Represents a documented Python module or package.
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.
Module-level docstring content.
Module-level documentation string, if present.
Dictionary mapping object names to their DocObject representations.
Mapping of object names to their corresponding +DocObject representations.
Initialize a new Module.
Initialize a Module instance.
The dotted path of the module.
Dotted import path identifying the module.
The module's docstring, if any.
Module-level documentation text, if available.
add_object(obj: DocObject) -> None -
add_object(obj: DocObject) -> None +
The object to add.
Documentation object to register as a top-level +member of the module.
get_all_objects() -> Iterable[DocObject] -
get_all_objects() -> Iterable[DocObject] +
Get all top-level objects in the module.
Return all top-level documentation objects in the module.
An iterable of DocObject instances.
An iterable of DocObject instances representing the
Iterable[DocObject]
module's public members.
get_object(name: str) -> DocObject -
get_object(name: str) -> DocObject +
Retrieve a documented object by name.
The name of the object.
Name of the object to retrieve.
If no object with the given name exists.
Project(name: str) -
Project(name: str) +
Represents a documentation project, serving as a container for modules.
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.
Dictionary mapping module paths to Module instances.
Mapping of module paths to Module instances.
Initialize a new Project.
Initialize a Project instance.
The name of the project.
Name used to identify the documentation project.
add_module(module: Module) -> None -
add_module(module: Module) -> None +
Add a module to the project.
Register a module in the project.
The module to add.
Module instance to add to the project.
get_all_modules() -> Iterable[Module] -
get_all_modules() -> Iterable[Module] +
Get all modules in the project.
Return all modules contained in the project.
An iterable of Module objects.
An iterable of Module instances.
get_module(path: str) -> Module -
get_module(path: str) -> Module +
The dotted path of the module (e.g., 'pkg.mod').
Fully qualified dotted module path (for example pkg.module).
pkg.module
The requested Module.
The corresponding Module instance.
If the module does not exist in the project.
get_module_list() -> list[str] -
get_module_list() -> list[str] +
Get the list of all module dotted paths.
Return the list of module import paths.
A list of module paths.
A list containing the dotted paths of all modules in the project.
This module defines the Module class, which represents a Python module or package -in the doc-forge documentation models. It acts as a container for top-level -documented objects.
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.
This module defines the DocObject class, the fundamental recursive unit of the -doc-forge documentation models. A DocObject represents a single Python entity -(class, function, method, or attribute) and its nested members.
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.
This module defines the Project class, the top-level container for a documented -project. It aggregates multiple Module instances into a single named entity.
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.
The docforge.nav package manages the mapping between the logical documentation -structure and the physical files on disk.
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.
resolve_nav
.md
MkDocsNavEmitter
This abstraction allows doc-forge to support complex grouping and ordering -independently of the source code's physical layout.
This layer separates documentation organization from the underlying source +code layout, enabling flexible grouping, ordering, and navigation structures +independent of module hierarchy.
Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible -navigation structure.
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.
ResolvedNav
nav
emit(nav: ResolvedNav) -> List[Dict[str, Any]] -
emit(nav: ResolvedNav) -> List[Dict[str, Any]] +
Generate a list of navigation entries for mkdocs.yml.
Generate a navigation structure for mkdocs.yml.
The resolved navigation data.
Resolved navigation data describing documentation groups +and their associated Markdown files.
A list of dictionary mappings representing the MkDocs navigation.
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
pages.
NavSpec(home: Optional[str], groups: Dict[str, List[str]]) -
NavSpec(home: Optional[str], groups: Dict[str, List[str]]) +
Parsed representation of the docforge navigation specification file.
Parsed representation of a navigation specification.
A NavSpec describes the intended documentation navigation layout before +it is resolved against the filesystem.
NavSpec
Path to the home document (e.g., 'index.md').
Relative path to the documentation home page (for example +index.md).
index.md
Mapping of group titles to lists of path patterns/globs.
Mapping of navigation group titles to lists of file patterns +or glob expressions.
Initialize a NavSpec.
Initialize a NavSpec instance.
The path to the home document.
Relative path to the home document.
A mapping of group names to lists of path patterns (globs).
Mapping of group names to lists of path patterns +(glob expressions).
all_patterns() -> List[str] -
all_patterns() -> List[str] +
Get all path patterns referenced in the specification.
Return all path patterns referenced by the specification.
A list of all patterns (home plus all groups).
A list containing the home document (if defined) and all
List[str]
group pattern entries.
classmethod
load(path: Path) -> NavSpec -
load(path: Path) -> NavSpec +
Load a NavSpec from a YAML file.
Load a navigation specification from a YAML file.
The filesystem path to the YAML file.
Filesystem path to the navigation specification file.
A NavSpec instance.
A NavSpec instance representing the parsed configuration.
If the path does not exist.
If the specified file does not exist.
If the file content is not a valid NavSpec mapping.
If the file contents are not a valid navigation +specification.
ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None) -
ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None) +
Represents a navigation structure where all patterns and paths have been -resolved against the actual filesystem contents.
Resolved navigation structure.
A ResolvedNav represents navigation data after glob patterns have been +expanded and paths validated against the filesystem.
Resolved relative path to the home page.
Relative path to the documentation home page.
Mapping of group titles to lists of absolute or relative Path objects.
Mapping of navigation group titles to lists of resolved +documentation file paths.
The relative path to the project home page.
Relative path to the home page within the documentation root.
A mapping of group names to their resolved filesystem paths.
Mapping of group titles to resolved documentation file paths.
The root documentation directory.
Root directory of the documentation source files.
all_files() -> Iterable[Path] -
all_files() -> Iterable[Path] +
Get an iterable of all resolved files in the navigation structure.
Iterate over all files referenced by the navigation structure.
An iterable of Path objects.
An iterable of Path objects representing documentation files.
RuntimeError
If the home page is defined but the documentation +root is not available for resolution.
load_nav_spec(path: Path) -> NavSpec -
load_nav_spec(path: Path) -> NavSpec +
Utility function to load a NavSpec from a file.
Load a navigation specification file.
This helper function reads a YAML navigation file and constructs a +corresponding NavSpec instance.
A loaded NavSpec instance.
A NavSpec instance representing the parsed specification.
If the specification file does not exist.
If the YAML structure is invalid.
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav -
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav +
Create a ResolvedNav by processing a NavSpec against the filesystem. -This expands globs and validates the existence of referenced files.
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.
The navigation specification to resolve.
Navigation specification describing documentation layout.
The root directory for documentation files.
Root directory containing documentation Markdown files.
A ResolvedNav instance.
A ResolvedNav instance containing validated navigation paths.
If a pattern doesn't match any files or the docs_root doesn't exist.
If the documentation root does not exist or a +navigation pattern does not match any files.
This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance -into the specific YAML-ready list structure expected by the MkDocs 'nav' -configuration.
MkDocs navigation emitter.
This module provides the MkDocsNavEmitter class, which converts a +ResolvedNav instance into the navigation structure required by the +MkDocs nav configuration.
This module contains the logic for resolving a NavSpec against the physical -filesystem. It expands globs and validates that all referenced documents -actually exist on disk.
Navigation resolution utilities.
This module resolves a NavSpec against the filesystem by expanding glob +patterns and validating that referenced documentation files exist.
This module defines the NavSpec class, which represents the user's intent for -documentation navigation as defined in a YAML specification (usually -docforge.nav.yml).
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).
This module defines the base interfaces and configuration containers for -doc-forge renderers. All renderer implementations should adhere to the -DocRenderer protocol.
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.
DocRenderer
Protocol defining the interface for documentation renderers.
Implementations of this protocol are responsible for transforming a +Project model into renderer-specific documentation sources.
Generate renderer-specific source files for the given project.
Generate renderer-specific documentation sources.
The project models containing modules and objects.
Project model containing modules and documentation objects.
Target directory for the generated files.
Directory where generated documentation sources +should be written.
RendererConfig(out_dir: Path, project: Project) -
RendererConfig(out_dir: Path, project: Project) +
Configuration container for documentation renderers.
A RendererConfig instance groups together the project model and the +output directory used during rendering.
RendererConfig
Directory where generated documentation files will be written.
Documentation project model to be rendered.
Initialize a RendererConfig instance.
The directory where documentation files should be written.
Target directory where documentation files should be written.
The introspected project models to be rendered.
Introspected project model to render.
The docforge.renderers package handles the transformation of the internal -documentation models into physical files formatted for specific documentation -engines.
Renderers layer for doc-forge.
The docforge.renderers package transforms the internal documentation +models into files formatted for specific documentation systems.
Renderers consume the doc-forge project model and generate output suitable +for documentation tools or machine interfaces.
Current implementations:
mkdocstrings
To add a new renderer, implement the DocRenderer protocol defined in -docforge.renderers.base.
docforge.renderers.base
New renderers can be added by implementing the DocRenderer protocol +defined in docforge.renderers.base.
MkDocsRenderer
Generates Markdown source files compatible with MkDocs Material -and mkdocstrings, ensuring:
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:
doc-forge is a renderer-agnostic Python documentation compiler designed for speed, flexibility, and beautiful output. It decouples the introspection of your code from the rendering process, allowing you to generate documentation for various platforms (starting with MkDocs) from a single internal models.
doc-forge is an \"AI-Native\" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
pip install doc-forge\n
Build Documentation: Introspect your package and generate documentation in one step: ```bash # Build MkDocs site doc-forge build --mkdocs --module my_package --site-name \"My Docs\"
Define Navigation: Create a docforge.nav.yml to organize your documentation: yaml home: my_package/index.md groups: Core API: - my_package/core/*.md Utilities: - my_package/utils.md
yaml home: my_package/index.md groups: Core API: - my_package/core/*.md Utilities: - my_package/utils.md
Preview: ```bash # Serve MkDocs site doc-forge serve --mkdocs
doc-forge build --mcp --module my_package ```
doc-forge serve --mcp ```
GriffeLoader()\n
load_module(path: str) -> Module\n
path
str
load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> Project\n
module_paths
Optional[str]
bool
generate_sources(project: Project, out_dir: Path) -> None\n
Renderer that generates Markdown source files formatted for the MkDocs 'mkdocstrings' plugin.
generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None\n
Produce a set of Markdown files in the output directory based on the provided Project models.
discover_module_paths(module_name: str, project_root: Path | None = None) -> List[str]\n
Rules: - Directory with init.py is treated as a package. - Any .py file is treated as a module. - All paths are converted to dotted module paths.
module_name
project_root
Path | None
The docforge.cli package provides the command-line interface for interacting with doc-forge.
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
This command orchestrates the full build process: 1. Introspects the code (Griffe) 2. Renders sources (MkDocs Markdown or MCP JSON) 3. (MkDocs only) Generates config and runs the final site build.
mcp
module
site_name
nav_file
template
Optional[Path]
mkdocs_yml
serve(mcp: bool, mkdocs: bool, module: Optional[str], mkdocs_yml: Path, out_dir: Path) -> None\n
tree(module: str, project_name: Optional[str]) -> None\n
Main entry point for the doc-forge CLI. This module delegates all command execution to docforge.cli.commands.
main() -> None\n
generate_resources(module: str, project_name: str | None, out_dir: Path) -> None\n
serve(module: str, mcp_root: Path) -> None\n
mcp_root
build(mkdocs_yml: Path) -> None\n
generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None\n
out
generate_sources(module: str, docs_dir: Path, project_name: str | None = None, module_is_source: bool | None = None) -> None\n
Directory where the generated Markdown files will be written.
serve(mkdocs_yml: Path) -> None\n
The docforge.loaders package is responsible for discovering Python source files and extracting their documentation using static analysis.
This module provides the GriffeLoader, which uses the 'griffe' library to introspect Python source code and populate the doc-forge Project models.
The docforge.models package provides the core data structures used to represent Python source code in a documentation-focused hierarchy.
These classes are designed to be renderer-agnostic, allowing the same internal representation to be transformed into various output formats (currently MkDocs).
DocObject(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None)\n
name
kind
signature
docstring
members
Dict[str, DocObject]
add_member(obj: DocObject) -> None\n
obj
get_all_members() -> Iterable[DocObject]\n
get_member(name: str) -> DocObject\n
Module(path: str, docstring: Optional[str] = None)\n
add_object(obj: DocObject) -> None\n
Add a documented object to the module.
get_all_objects() -> Iterable[DocObject]\n
get_object(name: str) -> DocObject\n
Project(name: str)\n
Name of the project.
modules
Dict[str, Module]
add_module(module: Module) -> None\n
get_all_modules() -> Iterable[Module]\n
Iterable[Module]
get_module(path: str) -> Module\n
Retrieve a module by its dotted path.
get_module_list() -> list[str]\n
list[str]
This module defines the Module class, which represents a Python module or package in the doc-forge documentation models. It acts as a container for top-level documented objects.
This module defines the DocObject class, the fundamental recursive unit of the doc-forge documentation models. A DocObject represents a single Python entity (class, function, method, or attribute) and its nested members.
This module defines the Project class, the top-level container for a documented project. It aggregates multiple Module instances into a single named entity.
The docforge.nav package manages the mapping between the logical documentation structure and the physical files on disk.
This abstraction allows doc-forge to support complex grouping and ordering independently of the source code's physical layout.
Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible navigation structure.
emit(nav: ResolvedNav) -> List[Dict[str, Any]]\n
NavSpec(home: Optional[str], groups: Dict[str, List[str]])\n
home
groups
Dict[str, List[str]]
all_patterns() -> List[str]\n
load(path: Path) -> NavSpec\n
ResolvedNav(home: str | None, groups: Dict[str, List[Path]], docs_root: Path | None = None)\n
Represents a navigation structure where all patterns and paths have been resolved against the actual filesystem contents.
Dict[str, List[Path]]
Initialize a ResolvedNav instance.
docs_root
all_files() -> Iterable[Path]\n
Iterable[Path]
load_nav_spec(path: Path) -> NavSpec\n
resolve_nav(spec: NavSpec, docs_root: Path) -> ResolvedNav\n
Create a ResolvedNav by processing a NavSpec against the filesystem. This expands globs and validates the existence of referenced files.
spec
This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance into the specific YAML-ready list structure expected by the MkDocs 'nav' configuration.
This module contains the logic for resolving a NavSpec against the physical filesystem. It expands globs and validates that all referenced documents actually exist on disk.
This module defines the NavSpec class, which represents the user's intent for documentation navigation as defined in a YAML specification (usually docforge.nav.yml).
The docforge.renderers package handles the transformation of the internal documentation models into physical files formatted for specific documentation engines.
To add a new renderer, implement the DocRenderer protocol defined in docforge.renderers.base.
This module defines the base interfaces and configuration containers for doc-forge renderers. All renderer implementations should adhere to the DocRenderer protocol.
Bases: Protocol
Protocol
RendererConfig(out_dir: Path, project: Project)\n
Generates Markdown source files compatible with MkDocs Material and mkdocstrings, ensuring:
MCPServer(mcp_root: Path, name: str)\n
MCP server for serving a pre-built MCP documentation bundle.
Initialize the MCPServer.
Path to the directory containing pre-built MCP JSON resources.
Name of the MCP server.
run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> None\n
Start the MCP server.
transport
Literal['stdio', 'sse', 'streamable-http']
MCP transport (default: streamable-http)
'streamable-http'
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.
doc-forge build --mkdocs --module my_package\n
doc-forge build --mcp --module my_package\n
doc-forge serve --mkdocs --module my_package\n
- module\n- class\n- function\n- method\n- property\n- attribute\n
Static analysis of modules, classes, functions, type hints, and docstrings.\n
Builds a semantic model describing symbols and relationships.\n
Renders documentation using interchangeable renderers.\n
Python package\n \u2193\nLoader (static analysis)\n \u2193\nSemantic model\n \u2193\nRenderer\n \u2193\nMkDocs site or MCP JSON\n
doc-forge serve --module my_package\n
GriffeLoader\ndiscover_module_paths\n
MkDocsRenderer\nMCPRenderer\n
main\n
models\n
## Summary\n## Installation\n## Quick start\n## Core concepts\n## Architecture\n## Rendering pipeline\n## CLI usage\n## Public API\n## Examples\n## Notes\n
'''\nFoo-bar processing framework.\n\nProvides tools for defining Foo objects and executing Bar pipelines.\n\n---\n\n# Installation\n\n pip install foo-bar\n\n---\n\n# Quick start\n\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n\n---\n\n# Public API\n\n Foo\n Bar\n BarEngine\n\n---\n'''\n
## Summary\n## Examples\n## Notes\n## Public API\n
'''\nFoo execution subsystem.\n\nProvides utilities for executing Foo objects through Bar stages.\n\n---\n\nExample:\n\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
Attributes:\nNotes:\nExample:\nRaises:\n
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 foo = Foo(\"example\", value=42)\n print(foo.name)\n '''\n
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 foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n '''\n
Args:\nReturns:\nRaises:\nYields:\nNotes:\nExample:\n
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 foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n '''\n
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 foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n\n Pipeline usage:\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n '''\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 container = FooContainer()\n\n foos = container.foos\n '''\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
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
Example:\n\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n
Example:\n Create foo:\n\n foo = Foo(\"example\")\n\n Run engine:\n\n engine = BarEngine([foo])\n engine.run()\n
---\n
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.
Creates an internal Griffe loader instance with dedicated collections for modules and source lines.
The module is introspected using Griffe and then transformed into a doc-forge Module model.
Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.
Optional override for the project name. Defaults to the top-level name of the first module.
If True, modules that fail to load will be skipped instead of raising an error.
If a module fails to load and skip_import_errors is False.
This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP).
The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json.
Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.
generate_readme(project: Project, docs_dir: Path, module_is_source: bool | None = None) -> None\n
Whether the module is treated as the project source root.
This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory.
If True, treat the specified module as the documentation root rather than nesting it inside a folder.
The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.
Root directory used to resolve module paths. If not provided, the current working directory is used.
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.
doc-forge <command> [options]\n
from docforge.cli import main\nmain()\n
Treat the specified module directory as the project root.
Directory where Markdown documentation sources will be generated.
This command introspects the specified module and prints a hierarchical representation of the discovered documentation objects, including modules, classes, functions, and members.
This module exposes the executable entry point that initializes the Click command group defined in docforge.cli.commands.
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.
The function performs project introspection, builds the internal documentation model, and renders MCP-compatible JSON resources to the specified output directory.
Python module import path used as the entry point for documentation generation.
Optional override for the project name used in generated documentation metadata.
Directory where MCP resources (index.json, nav.json, and module data) will be written.
The server exposes documentation resources such as project metadata, navigation structure, and module documentation through MCP endpoints.
Python module import path used to identify the served documentation instance.
Path to the directory containing the MCP documentation bundle (index.json, nav.json, and modules/).
If the MCP documentation bundle is missing required files or directories.
This function loads the MkDocs configuration and runs the MkDocs build command to generate the final static documentation site.
The configuration is created by combining a template configuration with a navigation structure derived from the docforge navigation specification.
Optional path to a custom MkDocs configuration template. If not provided, a built-in template will be used.
Destination path where the generated mkdocs.yml file will be written.
If the navigation specification or template file cannot be found.
This function introspects the specified module, builds the internal documentation model, and renders Markdown documentation files for use with MkDocs.
Optional override for the project name used in documentation metadata.
If True, treat the specified module directory as the project root rather than a nested module.
The server watches documentation files and automatically reloads the site when changes are detected.
The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.
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.
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.
The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.
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.
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).
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.
Type of object (for example class, function, method, or attribute).
This is typically used when attaching methods to classes or nested objects to their parent containers.
A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.
Mapping of object names to their corresponding DocObject representations.
Documentation object to register as a top-level member of the module.
A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.
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.
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.
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.
The docforge.nav package manages the relationship between the logical documentation structure defined by the user and the physical documentation files generated on disk.
This layer separates documentation organization from the underlying source code layout, enabling flexible grouping, ordering, and navigation structures independent of module hierarchy.
The emitter transforms a ResolvedNav object into the YAML-compatible list structure expected by the MkDocs nav configuration field.
Resolved navigation data describing documentation groups and their associated Markdown files.
A NavSpec describes the intended documentation navigation layout before it is resolved against the filesystem.
Relative path to the documentation home page (for example index.md).
Mapping of navigation group titles to lists of file patterns or glob expressions.
Mapping of group names to lists of path patterns (glob expressions).
If the file contents are not a valid navigation specification.
A ResolvedNav represents navigation data after glob patterns have been expanded and paths validated against the filesystem.
Mapping of navigation group titles to lists of resolved documentation file paths.
If the home page is defined but the documentation root is not available for resolution.
This helper function reads a YAML navigation file and constructs a corresponding NavSpec instance.
The function expands glob patterns defined in a NavSpec and verifies that referenced documentation files exist within the documentation root.
If the documentation root does not exist or a navigation pattern does not match any files.
This module provides the MkDocsNavEmitter class, which converts a ResolvedNav instance into the navigation structure required by the MkDocs nav configuration.
This module resolves a NavSpec against the filesystem by expanding glob patterns and validating that referenced documentation files exist.
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).
The docforge.renderers package transforms the internal documentation models into files formatted for specific documentation systems.
Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.
New renderers can be added by implementing the DocRenderer protocol defined in docforge.renderers.base.
This module defines the base protocol and configuration container used by doc-forge renderers. Concrete renderer implementations should implement the DocRenderer protocol.
Implementations of this protocol are responsible for transforming a Project model into renderer-specific documentation sources.
Directory where generated documentation sources should be written.
A RendererConfig instance groups together the project model and the output directory used during rendering.
This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.
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.
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.
Directory containing the generated MCP documentation bundle (for example index.json, nav.json, and modules/).
modules/
Identifier used for the MCP server instance.
Transport mechanism used by the MCP server. Supported options include stdio, sse, and streamable-http.
stdio
sse
streamable-http
This module exposes server implementations used to provide live access +to generated documentation resources. Currently, it includes the MCP +documentation server.
MCPServer(mcp_root: Path, name: str) -
MCPServer(mcp_root: Path, name: str) +
The server exposes documentation resources and diagnostic tools through +MCP endpoints backed by JSON files generated by the MCP renderer.
Directory containing the generated MCP documentation +bundle (for example index.json, nav.json, and +modules/).
run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> None -
run(transport: Literal['stdio', 'sse', 'streamable-http'] = 'streamable-http') -> None +
Transport mechanism used by the MCP server. Supported +options include stdio, sse, and streamable-http.