aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

google styled doc string

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-02-28 18:53:02 +05:30
parent b5379cd82e
commit 87a7f4eee1
1 changed files with 389 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

613
docforge/__init__.py
View File

@@ -1,270 +1,435 @@
"""
Renderer-agnostic Python documentation compiler that converts docstrings into
structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
Renderer-agnostic Python documentation compiler that converts Python docstrings
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
`doc-forge` statically analyzes source code, builds a semantic model of modules,
classes, functions, and attributes, and renders that model into documentation
outputs without executing user code.
`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
## Installation
Install using pip:
pip install doc-forge
---
## Quick start
Generate a MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package
Generate MCP JSON documentation:
doc-forge build --mcp --module my_package
Serve documentation locally:
doc-forge serve --mkdocs --module my_package
---
## Core concepts
**Loader**
Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model**
Structured, renderer-agnostic representation of the API.
**Renderer**
Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol**
Any documentable object:
- module
- class
- function
- method
- property
- attribute
---
## Architecture
`doc-forge` follows a compiler architecture:
1. **Front-end (Introspection)**
Static analysis of modules, classes, functions, signatures, and docstrings.
Front-end:
2. **Middle-end (Semantic Model)**
Renderer-neutral structured representation of your API.
Static analysis of modules, classes, functions, type hints, and docstrings.
3. **Back-end (Renderers)**
Middle-end:
Builds a semantic model describing symbols and relationships.
Back-end:
Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation.
* MkDocs → human documentation
* MCP JSON → AI-readable documentation
---
# Docstring Writing Standard
## Rendering pipeline
Docstrings are the single source of truth. `doc-forge` does not generate content.
It compiles and renders what you write.
Typical flow:
Python package
↓
Loader (static analysis)
↓
Semantic model
↓
Renderer
↓
MkDocs site or MCP JSON
---
## CLI usage
Build MkDocs documentation:
doc-forge build --mkdocs --module my_package
Build MCP documentation:
doc-forge build --mcp --module my_package
Serve MkDocs locally:
doc-forge serve --module my_package
---
## Public API
Loaders:
GriffeLoader
discover_module_paths
Renderers:
MkDocsRenderer
MCPRenderer
CLI:
main
Models:
models
---
## Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs
and remain machine-parsable.
Docstrings are the single source of truth. doc-forge compiles docstrings but does
not generate documentation content.
Documentation follows the Python import hierarchy.
---
# Package docstring (`package/__init__.py`) — Full user guide
### General rules
This is the landing page. A developer must be able to install and use the
package after reading only this docstring.
Use Markdown headings at package and module level.
## Example:
Use Google-style sections at class and function level.
'''
Short description of what this package provides.
Supported structured sections:
# Installation
Args:
Returns:
Raises:
Yields:
Attributes:
Notes:
Example:
Examples:
See Also:
```bash
pip install my-package
```
Indent section contents using four spaces.
# Quick start
Type information must come from function signatures, not duplicated prose.
```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,
value1: str,
value2: str | None = "default value",
value3: str | None = None,
) -> str:
'''
Process an input value.
---
Avoid NumPy-style sections such as:
Parameters
----------
value1 : str
required: True
value to be processed
Example:
'string'
Returns tables
value2 : str
required: False
default: "default value"
value to be processed
Example:
'string'
Avoid pseudo-fields such as:
required:
default:
---
### Package docstrings
Package docstrings act as the documentation home page.
They should include:
Summary
---
Installation
Quick start
Core concepts
Architecture
Rendering pipeline
CLI usage
Public API
Examples
Notes
Example:
'''
My package summary.
value3 : str
required: False
value to be processed
Example:
'string'
---
Returns
-------
processed value : str
result after processing value
## Installation
pip install my-package
## Quick start
from my_package import Foo
foo = Foo()
foo.run()
'''
---
### Module docstrings
Module docstrings describe subsystems.
Recommended sections:
Summary
---
Examples
Notes
Public API
Example:
'''
Execution subsystem.
---
Behavior
--------
- behaviour 1
- behaviour 2
Example:
from my_package.engine import Engine
engine = Engine(nodes)
'''
---
### Class docstrings
Class docstrings define object responsibility and lifecycle.
Supported sections:
Attributes:
Notes:
Example:
Raises:
Example:
class Engine:
'''
Executes pipelines.
Attributes:
nodes (tuple[Node, ...]):
Execution nodes.
Notes:
Guarantees:
- deterministic execution
- immutable state propagation
Lifecycle:
- reusable across executions
Example:
Basic usage:
engine = Engine(nodes)
engine.run(state)
'''
---
### Function and method docstrings
Function docstrings define API contracts.
Supported sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
def run(state: State) -> list[State]:
'''
Execute pipeline.
Args:
state (State):
Initial execution state.
Returns:
list[State]:
Resulting execution states.
Notes:
Guarantees:
- state is not modified
'''
---
### Property docstrings
Properties must document return values.
Example:
@property
def nodes(self) -> tuple[Node, ...]:
'''
Return execution nodes.
Returns:
tuple[Node, ...]:
Configured nodes.
'''
---
### Attribute documentation
Attributes must be documented in the class docstring using Attributes:.
Example:
class State:
'''
Execution state.
Attributes:
payload (dict):
Immutable execution data.
depth (int):
Distance from root state.
'''
---
### Notes subsection grouping
Subsections may be grouped using labeled blocks:
Notes:
Guarantees:
- deterministic execution
Lifecycle:
- reusable instance
Thread safety:
- safe for concurrent use
Do not use horizontal separators inside structured sections.
---
### Example formatting
Use indentation for examples:
Example:
Basic usage:
engine = Engine(nodes)
engine.run(state)
Multiple examples may be grouped using labels.
---
### Separator rules
Use horizontal separators only at docstring root level:
---
'''
```
Do not use separators inside:
Args:
Returns:
Notes:
Attributes:
---
# Attribute docstrings (optional)
### Parsing guarantees
## Example:
GSDFC ensures doc-forge can deterministically extract:
```python
class Class
'''
attribute1 : str
required: True
default: "default value"
attribute description
symbol type
symbol name
parameters
return types
attributes
examples
structured notes
attribute2 : str
required: False
attribute description
This enables reliable MkDocs rendering and MCP export.
attribute2 : str
required: False
default: "default value"
attribute description
'''
attribute1: str = "default value"
attribute2: str | None = None
attribute3: str | None = "default value"
```
---
# Writing Rules
## Notes
**Heading hierarchy**
doc-forge never executes analyzed modules.
Module docstring
- Examples
- Usage
- Core concepts
- Public API
Class docstring
- Attributes
- Execution contract
- Lifecycle
- Thread safety
- Notes
Method docstring
- Parameters
- Returns
- Raises
- Yields
- Behavior
**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.
---
Documentation is generated entirely through static analysis.
"""
from .loaders import GriffeLoader, discover_module_paths