Vishesh 'ironeagle' Bangotra
2ed962d639
Reviewed-on: #3 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
99 lines
3.7 KiB
Python
99 lines
3.7 KiB
Python
"""
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|
|
"""
|
|
|
|
from .loaders import GriffeLoader, discover_module_paths
|
|
from .renderers import MkDocsRenderer, MCPRenderer
|
|
from .cli import main
|
|
from . import models
|
|
|
|
__all__ = [
|
|
"GriffeLoader",
|
|
"discover_module_paths",
|
|
"MkDocsRenderer",
|
|
"MCPRenderer",
|
|
"models",
|
|
"main",
|
|
]
|