doc-forge

A renderer-agnostic Python documentation compiler that converts Python source code and docstrings into a structured, semantic documentation model and emits multiple downstream representations.

Features

• Single Source of Truth: Python source code and docstrings are the only authoritative input
• Renderer Agnosticism: MkDocs, Sphinx, MCP, or future renderers don't influence the core model
• Deterministic Output: Given the same codebase, outputs are reproducible
• AI-Native Documentation: Structured, queryable, and machine-consumable
• Library-First Design: All functionality accessible as a Python API

Installation

pip install doc-forge

Optional Dependencies

# For MkDocs rendering
pip install doc-forge[mkdocs]

# For Sphinx rendering  
pip install doc-forge[sphinx]

# For MCP support
pip install doc-forge[mcp]

# For development
pip install doc-forge[dev]

Quick Start

Command Line Interface

# Generate MkDocs documentation
doc-forge generate --renderer mkdocs mypackage

# Build final HTML documentation
doc-forge build --renderer mkdocs mypackage

# Serve documentation locally
doc-forge serve --renderer mkdocs mypackage

# Export to MCP format
doc-forge export mypackage

# Start live MCP server
doc-forge server mypackage

Python API

from docforge.loaders import GriffeLoader
from docforge.renderers import MkDocsRenderer
from pathlib import Path

# Load your project
loader = GriffeLoader()
project = loader.load_project(["mypackage", "mypackage.utils"])

# Generate MkDocs sources
renderer = MkDocsRenderer()
renderer.generate_sources(project, Path("docs"))

# Build final documentation
from docforge.renderers.base import RendererConfig

config = RendererConfig(Path("docs"), project)
renderer.build(config)

Architecture

doc-forge follows this high-level architecture:

Python Source Code
        ↓
Introspection Layer (Griffe)
        ↓
Documentation Model (doc-forge core)
        ↓
Renderer / Exporter Layer
   ├── MkDocs
   ├── Sphinx
   ├── MCP (static JSON)
   └── MCP Server (live)

Core Components

Documentation Model

• Project: Root container for all documentation
• Module: Represents Python modules
• DocObject: Base class for classes, functions, variables, etc.
• Navigation: Hierarchical structure for browsing

Renderers

• MkDocs Renderer: Generates Markdown with mkdocstrings directives
• Sphinx Renderer: Generates reStructuredText with autodoc directives

Exporters

• MCP Exporter: Creates static JSON bundles for machine consumption
• MCP Server: Live server for real-time documentation access

CLI Commands

generate

Generate renderer-specific source files without building final artifacts.

doc-forge generate --renderer mkdocs --out-dir docs mypackage

build

Build final documentation artifacts (HTML, etc.).

doc-forge build --renderer sphinx mypackage

serve

Start a local development server.

doc-forge serve --renderer mkdocs --port 9000 mypackage

export

Export to MCP format for machine consumption.

doc-forge export --out-dir mcp mypackage

server

Start live MCP server for real-time access.

doc-forge server --host 0.0.0.0 --port 8080 mypackage

Configuration

doc-forge is designed to work with minimal configuration. Most settings are derived automatically from your Python code structure.

MkDocs Configuration

The MkDocs renderer automatically generates mkdocs.yml with sensible defaults:

site_name: Your Project
plugins:
  - mkdocstrings
theme:
  name: material

Sphinx Configuration

The Sphinx renderer automatically generates conf.py with standard extensions:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode', 
    'sphinx.ext.napoleon',
]

MCP Integration

doc-forge provides two ways to integrate with MCP (Model Context Protocol):

Static Export

doc-forge export mypackage

Creates a static JSON bundle in mcp/ directory that can be loaded by MCP clients.

Live Server

doc-forge server mypackage

Starts a live MCP server providing real-time access to documentation resources:

• docs://index - Project metadata
• docs://nav - Navigation structure
• docs://module/{module} - Individual module data

Development

Setup

git clone https://github.com/doc-forge/doc-forge
cd doc-forge
pip install -e ".[dev]"

Running Tests

pytest

Code Quality

black docforge/
ruff check docforge/
mypy docforge/

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Philosophy

doc-forge is built on these core principles:

1. Single Source of Truth: Python source code and docstrings are the only authoritative input
2. Renderer Agnosticism: The core model contains no renderer-specific logic
3. Deterministic Output: Same input always produces same output
4. AI-Native Documentation: Documentation must be structured, queryable, and machine-consumable
5. Library-First: All functionality must be accessible as a Python API

---

doc-forge turns Python code into structured knowledge and emits it through multiple human and machine interfaces.