240 lines
4.1 KiB
Python
240 lines
4.1 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:
|
|
|
|
'''
|
|
Short description of what this package provides.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install my-package
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```python
|
|
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:
|
|
|
|
'''
|
|
Provides core functionality.
|
|
|
|
## Usage
|
|
|
|
```python
|
|
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.
|
|
|
|
Parameters
|
|
----------
|
|
value : str
|
|
value to be processed
|
|
Example:
|
|
'string'
|
|
|
|
Returns
|
|
-------
|
|
processed value : str
|
|
result after processing value
|
|
---
|
|
|
|
Behavior
|
|
--------
|
|
- behaviour 1
|
|
- behaviour 2
|
|
'''
|
|
```
|
|
---
|
|
|
|
## Attribute docstrings (optional)
|
|
|
|
Example:
|
|
|
|
```python
|
|
class Class
|
|
'''
|
|
attribute1 : str
|
|
required: True
|
|
default: "default value"
|
|
attribute description
|
|
|
|
attribute2 : str
|
|
required: False
|
|
attribute description
|
|
|
|
attribute2 : str
|
|
required: False
|
|
default: "default value"
|
|
attribute description
|
|
'''
|
|
|
|
attribute1: str = "default value"
|
|
attribute2: str | None = None
|
|
attribute3: str | None = "default value"
|
|
```
|
|
---
|
|
|
|
## Writing Rules
|
|
|
|
**Required**
|
|
|
|
* Use Markdown headings
|
|
* Use Markdown line separator `---`
|
|
* Line separator should be followed by a blank line
|
|
* 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",
|
|
]
|