Docforge

docforge

doc-forge

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.

Available Commands

• build: Build documentation (MkDocs site or MCP resources).
• serve: Serve documentation (MkDocs or MCP).
• tree: Visualize the introspected project structure.

Installation

Install using pip with the optional mkdocs dependencies for a complete setup:

pip install doc-forge

Quick Start

1. 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"

   Build MCP resources

   doc-forge build --mcp --module my_package ```

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

3. Preview: ```bash # Serve MkDocs site doc-forge serve --mkdocs

   Serve MCP documentation

   doc-forge serve --mcp ```

Project Structure

• docforge.loaders: Introspects source code using static analysis (griffe).
• docforge.models: The internal representation of your project, modules, and objects.
• docforge.renderers: Converters that turn the models into physical files.
• docforge.nav: Managers for logical-to-physical path mapping and navigation.

GriffeLoader

GriffeLoader()

Loads Python modules and extracts documentation using the Griffe introspection engine.

Initialize the GriffeLoader.

load_module

load_module(path: str) -> Module

Load a single module and convert its introspection data into the docforge models.

Parameters:

Name	Type	Description	Default
path	str	The dotted path of the module to load.	required

Returns:

Type	Description
Module	A Module instance.

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

Parameters:

Name	Type	Description	Default
module_paths	List[str]	A list of dotted paths to the modules to load.	required
project_name	Optional[str]	Optional name for the project. Defaults to the first module name.	None
skip_import_errors	bool	If True, modules that fail to import will be skipped.	None

Returns:

Type	Description
Project	A Project instance containing the loaded modules.

MCPRenderer

Renderer that emits MCP-native JSON resources from docforge models.

generate_sources

generate_sources(project: Project, out_dir: Path) -> None

Generate MCP-compatible JSON resources and navigation for the project.

Parameters:

Name	Type	Description	Default
project	Project	The project model to render.	required
out_dir	Path	Target directory for the generated JSON files.	required

MkDocsRenderer

Renderer that generates Markdown source files formatted for the MkDocs 'mkdocstrings' plugin.

generate_sources

generate_sources(project: Project, out_dir: Path) -> None

Produce a set of Markdown files in the output directory based on the provided Project models.

Parameters:

Name	Type	Description	Default
project	Project	The project models to render.	required
out_dir	Path	Target directory for documentation files.	required

discover_module_paths

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.

Parameters:

Name	Type	Description	Default
module_name	str	The name of the package to discover.	required
project_root	Path | None	The root directory of the project. Defaults to current working directory.	None

Returns:

Type	Description
List[str]	A sorted list of dotted module paths.