# 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

```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.loader 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 turns Python code into structured knowledge and emits it through multiple human and machine interfaces.*