221 lines
3.5 KiB
Python
221 lines
3.5 KiB
Python
"""
|
|
Renderer-agnostic Python documentation compiler that converts docstrings into
|
|
structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
|
|
|
|
`doc-forge` statically analyzes your source code, builds a semantic model of
|
|
modules and objects, and renders that model into documentation outputs without
|
|
executing your code.
|
|
|
|
---
|
|
|
|
## Core Philosophy
|
|
|
|
`doc-forge` follows a compiler architecture:
|
|
|
|
1. **Front-end (Introspection)**
|
|
Static analysis of modules, classes, functions, signatures, and docstrings.
|
|
|
|
2. **Middle-end (Semantic Model)**
|
|
Renderer-neutral structured representation of your API.
|
|
|
|
3. **Back-end (Renderers)**
|
|
|
|
* MkDocs → human documentation
|
|
* MCP JSON → AI-readable documentation
|
|
|
|
The atomic unit of documentation is the Python import path.
|
|
|
|
Example:
|
|
|
|
```python
|
|
from my_package.foo import Bar
|
|
```
|
|
|
|
---
|
|
|
|
## Docstring Writing Standard
|
|
|
|
Docstrings are the single source of truth. `doc-forge` does not generate content.
|
|
It compiles and renders what you write.
|
|
|
|
Documentation follows the Python import hierarchy.
|
|
|
|
---
|
|
|
|
## Package docstring (`package/__init__.py`) — Full user guide
|
|
|
|
This is the landing page. A developer must be able to install and use the
|
|
package after reading only this docstring.
|
|
|
|
Example:
|
|
|
|
```python
|
|
'''
|
|
my_package
|
|
|
|
Short description of what this package provides.
|
|
|
|
## Installation
|
|
|
|
pip install my-package
|
|
|
|
## Quick start
|
|
|
|
from my_package.foo import Bar
|
|
|
|
bar = Bar()
|
|
result = bar.process("example")
|
|
|
|
## Core concepts
|
|
|
|
Bar
|
|
Primary object exposed by the package.
|
|
|
|
foo module
|
|
Provides core functionality.
|
|
|
|
## Typical workflow
|
|
|
|
1. Import public objects
|
|
2. Initialize objects
|
|
3. Call methods
|
|
|
|
## Public API
|
|
|
|
foo.Bar
|
|
foo.helper_function
|
|
'''
|
|
```
|
|
|
|
---
|
|
|
|
## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
|
|
|
|
Explains a specific subsystem.
|
|
|
|
Example:
|
|
|
|
```python
|
|
'''
|
|
foo subsystem.
|
|
|
|
Provides core functionality.
|
|
|
|
## Usage
|
|
|
|
from my_package.foo import Bar
|
|
|
|
bar = Bar()
|
|
bar.process("example")
|
|
'''
|
|
```
|
|
|
|
---
|
|
|
|
## Class docstring — Object contract
|
|
|
|
Defines responsibility and behavior.
|
|
|
|
Example:
|
|
|
|
```python
|
|
class Bar:
|
|
'''
|
|
Performs processing on input data.
|
|
|
|
Instances may be reused across multiple calls.
|
|
'''
|
|
```
|
|
|
|
Include:
|
|
|
|
* Responsibility
|
|
* Lifecycle expectations
|
|
* Thread safety (if relevant)
|
|
* Performance characteristics (if relevant)
|
|
|
|
---
|
|
|
|
## Function and method docstrings — API specification
|
|
|
|
Example:
|
|
|
|
```python
|
|
def process(self, value: str) -> str:
|
|
'''
|
|
Process an input value.
|
|
|
|
Args:
|
|
value:
|
|
Input string.
|
|
|
|
Returns:
|
|
Processed string.
|
|
|
|
Raises:
|
|
ValueError:
|
|
If the input is invalid.
|
|
'''
|
|
```
|
|
|
|
---
|
|
|
|
## Attribute docstrings (optional)
|
|
|
|
Example:
|
|
|
|
```python
|
|
self.name: str
|
|
'''Identifier used during processing.'''
|
|
```
|
|
|
|
---
|
|
|
|
## Writing Rules
|
|
|
|
**Required**
|
|
|
|
* Use Markdown headings
|
|
* Provide real import examples
|
|
* Document all public APIs
|
|
* Keep descriptions precise and factual
|
|
|
|
**Avoid**
|
|
|
|
* Plain-text separators like `====`
|
|
* Duplicate external documentation
|
|
* Informal or conversational language
|
|
|
|
---
|
|
|
|
## How doc-forge uses these docstrings
|
|
|
|
Build MkDocs site:
|
|
|
|
```bash
|
|
doc-forge build --mkdocs --module my_package
|
|
```
|
|
|
|
Build MCP documentation:
|
|
|
|
```bash
|
|
doc-forge build --mcp --module my_package
|
|
```
|
|
|
|
Both outputs are generated directly from docstrings.
|
|
"""
|
|
|
|
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",
|
|
]
|