init docforge lib

README.md

@@ -0,0 +1,243 @@
+# 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.*