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.

Core Philosophy

doc-forge operates on two fundamental principles:

1. The Atomic Unit is a Python Import Path: Documentation is organized around the semantic structure of your code (e.g., mypackage.utils), not the filesystem.
2. The Documentation Compiler Paradigm: We separate documentation into three distinct phases:
   • Front-end (Introspection): Static analysis of source code and docstrings.
   • Middle-end (Semantic Model): A renderer-neutral internal representation.
   • Back-end (Renderers): Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.

Documentation Design

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:

For Humans (Readability & Structure)

• __init__.py as Landing Pages: Use the docstring of your package's __init__.py as the home page. Include overviews, installation instructions, and high-level examples here.
• Single Source of Truth: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
• Semantic Hierarchy: Use standard Markdown headers to structure complex module documentation.

For LLMs (AI-Native Knowledge)

• Model Context Protocol (MCP): doc-forge exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
• Canonical Paths: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
• Type Annotations: While not in docstrings, doc-forge (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.

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, module_is_source: bool | None = None) -> 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
module_is_source	bool | None	Module is the source folder and to be treated as the root folder.	None

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.