aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated template for mkdocs and rendered MCP docs and site

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-07 16:07:18 +05:30
parent 17d39a3e88
commit 7f5dd7e5be
31 changed files with 1308 additions and 936 deletions
Download Patch File Download Diff File Expand all files Collapse all files

768
README.md
View File

@@ -1,244 +1,534 @@
# doc-forge
# docforge
A renderer-agnostic Python documentation compiler that converts Python source code and docstrings into a structured, semantic documentation model and emits multiple downstream representations.
Renderer-agnostic Python documentation compiler that converts Python docstrings
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
## 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
```bash
pip install doc-forge
```
### Optional Dependencies
```bash
# 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
```bash
# 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
```python
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.
```bash
doc-forge generate --renderer mkdocs --out-dir docs mypackage
```
### `build`
Build final documentation artifacts (HTML, etc.).
```bash
doc-forge build --renderer sphinx mypackage
```
### `serve`
Start a local development server.
```bash
doc-forge serve --renderer mkdocs --port 9000 mypackage
```
### `export`
Export to MCP format for machine consumption.
```bash
doc-forge export --out-dir mcp mypackage
```
### `server`
Start live MCP server for real-time access.
```bash
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:
```yaml
site_name: Your Project
plugins:
- mkdocstrings
theme:
name: material
```
### Sphinx Configuration
The Sphinx renderer automatically generates `conf.py` with standard extensions:
```python
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
```bash
doc-forge export mypackage
```
Creates a static JSON bundle in `mcp/` directory that can be loaded by MCP clients.
### Live Server
```bash
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
```bash
git clone https://github.com/doc-forge/doc-forge
cd doc-forge
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
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` 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 turns Python code into structured knowledge and emits it through multiple human and machine interfaces.*
## Installation
Install using pip:
pip install doc-forge
---
## Quick start
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
---
## Core concepts
**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:
- module
- class
- function
- method
- property
- attribute
---
## Architecture
`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.
---
## Rendering pipeline
Typical flow:
Python package
↓
Loader (static analysis)
↓
Semantic model
↓
Renderer
↓
MkDocs site or MCP JSON
---
## CLI usage
Build MkDocs documentation:
doc-forge build --mkdocs --module my_package
Build MCP documentation:
doc-forge build --mcp --module my_package
Serve MkDocs locally:
doc-forge serve --module my_package
---
## Public API
Loaders:
GriffeLoader
discover_module_paths
Renderers:
MkDocsRenderer
MCPRenderer
CLI:
main
Models:
models
---
# Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
- Docstrings are the single source of truth.
- doc-forge compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring.
---
## General rules
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Indent section contents using four spaces.
- Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form.
- Sections are separated by ```---```
---
## Package docstrings
- Package docstrings act as the documentation home page.
Recommended sections:
## Summary
## Installation
## Quick start
## Core concepts
## Architecture
## Rendering pipeline
## CLI usage
## Public API
## Examples
## Notes
Example:
Package Doc String:
'''
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
---
'''
---
## Module docstrings
- Module docstrings describe a subsystem.
Recommended sections:
## Summary
## Examples
## Notes
## Public API
Example:
Module Doc String:
'''
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()
---
'''
---
## Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
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:
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()
'''
---
## Function and method docstrings
- Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
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:
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 docstrings
- Properties must document return values.
Example:
Property Doc String:
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
container = FooContainer()
foos = container.foos
'''
---
## Attribute documentation
- Document attributes in class docstrings using Attributes:.
Example:
Attribute Doc String:
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
---
## Notes subsection grouping
- Group related information using labeled subsections.
Example:
Notes Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
## Example formatting
- Use indentation for examples.
Example:
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.
---
## Separator rules
Use horizontal separators only at docstring root level to separate sections:
---
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract:
- symbol kind (module, class, function, property, attribute)
- symbol name
- parameters
- return values
- attributes
- examples
- structured Notes subsections
This enables:
- reliable MkDocs rendering
- deterministic MCP export
- accurate AI semantic interpretation
---
Notes:
- doc-forge never executes analyzed modules.
- Documentation is generated entirely through static analysis.