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

formatting for examples and header sections

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 15:05:38 +05:30
parent 3dc6ac9427
commit f73282b997
3 changed files with 739 additions and 727 deletions
Download Patch File Download Diff File Expand all files Collapse all files

726
README.md
View File

@@ -9,78 +9,95 @@ outputs without executing user code.
---
## Installation
# Installation
Install using pip:
pip install doc-forge
```bash
pip install doc-forge
```
---
## Quick start
# CLI usage
Generate a MkDocs site from a Python package:
## Generate an MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package
```bash
doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation:
## Generate MCP JSON documentation:
doc-forge build --mcp --module my_package
```bash
doc-forge build --mcp --module my_package
```
Serve documentation locally:
doc-forge serve --mkdocs --module my_package
## Generate MkDocs site and MCP JSON documentation:
```bash
doc-forge build --mcp --mkdocs --module my_package
```
## Serve MkDocs locally:
```bash
doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
---
## Core concepts
**Loader**
# Core concepts
## Loader
Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model**
## Semantic model
Structured, renderer-agnostic representation of the API.
**Renderer**
## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol**
## Symbol
Any documentable object
Any documentable object:
- module
- class
- function
- method
- property
- attribute
- module
- class
- function
- method
- property
- attribute
---
## Architecture
# Architecture
`doc-forge` follows a compiler architecture:
Front-end:
## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings.
Static analysis of modules, classes, functions, type hints, and docstrings.
Middle-end:
## Middle-end:
Builds a semantic model describing symbols and relationships.
Builds a semantic model describing symbols and relationships.
Back-end:
## Back-end:
Renders documentation using interchangeable renderers.
Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation.
---
## Rendering pipeline
# Rendering pipeline
Typical flow:
@@ -96,44 +113,6 @@ Typical flow:
---
## 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 by doc-forge and AI tooling.
@@ -149,299 +128,12 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Indent section contents using four spaces.
- Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form.
- Sections are separated by ```---```
---
## Package docstrings
- Package docstrings act as the documentation home page.
Recommended sections:
## Summary
## Installation
## Quick start
## Core concepts
## Architecture
## Rendering pipeline
## CLI usage
## Public API
## Examples
## Notes
Example:
Package Doc String:
'''
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
pip install foo-bar
---
# Quick start
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
---
# Public API
Foo
Bar
BarEngine
---
'''
---
## Module docstrings
- Module docstrings describe a subsystem.
Recommended sections:
## Summary
## Examples
## Notes
## Public API
Example:
Module Doc String:
'''
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
---
'''
---
## Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
foo = Foo("example", value=42)
print(foo.name)
'''
Complex Bar:
class BarEngine:
'''
Executes Foo objects through Bar stages.
Attributes:
foos (tuple[Foo, ...]):
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
'''
---
## Function and method docstrings
- Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
'''
Multiple Examples:
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
'''
Combine two Foo instances.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
Pipeline usage:
engine = BarEngine([foo1, foo2])
engine.run()
'''
---
## Property docstrings
- Properties must document return values.
Example:
Property Doc String:
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
container = FooContainer()
foos = container.foos
'''
---
## Attribute documentation
- Document attributes in class docstrings using Attributes:.
Example:
Attribute Doc String:
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
---
## Notes subsection grouping
- Group related information using labeled subsections.
@@ -468,26 +160,33 @@ Example:
## Example formatting
- Use indentation for examples.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
@@ -496,8 +195,9 @@ Avoid fenced code blocks inside structured sections.
## Separator rules
Use horizontal separators only at docstring root level to separate sections:
---
```markdown
---
```
Allowed locations:
@@ -509,6 +209,312 @@ Do not use separators inside code sections.
---
## Package docstrings
- Package docstrings act as the documentation home page.
Recommended sections:
# Summary
# Installation
# Quick start
# CLI usage
# Core concepts
# Architecture
# Rendering pipeline
# Examples
# Notes
Example:
Package Doc String:
'''
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
```bash
pip install foo-bar
```
---
# Quick start
```python
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
```
---
'''
---
## Module docstrings
- Module docstrings describe a subsystem.
Recommended sections:
# Summary
# Examples
# Notes
Example:
Module Doc String:
'''
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
```python
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
```
---
'''
---
## Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
```python
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
```python
foo = Foo("example", value=42)
print(foo.name)
```
'''
```
Complex Bar:
```python
class BarEngine:
'''
Executes Foo objects through Bar stages.
Attributes:
foos (tuple[Foo, ...]):
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
```python
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
## Function and method docstrings
- Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
```python
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
```
'''
```
Multiple Examples:
```python
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
'''
Combine two Foo instances.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
```python
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
```
Pipeline usage:
```python
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
## Property docstrings
- Properties must document return values.
Example:
Property Doc String:
```python
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
```python
container = FooContainer()
foos = container.foos
```
'''
```
---
## Attribute documentation
- Document attributes in class docstrings using Attributes:.
Example:
Attribute Doc String:
```python
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
```
---
## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract:

726
docforge/__init__.py
View File

@@ -8,78 +8,95 @@ outputs without executing user code.
---
## Installation
# Installation
Install using pip:
pip install doc-forge
```bash
pip install doc-forge
```
---
## Quick start
# CLI usage
Generate a MkDocs site from a Python package:
## Generate an MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package
```bash
doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation:
## Generate MCP JSON documentation:
doc-forge build --mcp --module my_package
```bash
doc-forge build --mcp --module my_package
```
Serve documentation locally:
doc-forge serve --mkdocs --module my_package
## Generate MkDocs site and MCP JSON documentation:
```bash
doc-forge build --mcp --mkdocs --module my_package
```
## Serve MkDocs locally:
```bash
doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
---
## Core concepts
**Loader**
# Core concepts
## Loader
Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model**
## Semantic model
Structured, renderer-agnostic representation of the API.
**Renderer**
## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol**
## Symbol
Any documentable object
Any documentable object:
- module
- class
- function
- method
- property
- attribute
- module
- class
- function
- method
- property
- attribute
---
## Architecture
# Architecture
`doc-forge` follows a compiler architecture:
Front-end:
## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings.
Static analysis of modules, classes, functions, type hints, and docstrings.
Middle-end:
## Middle-end:
Builds a semantic model describing symbols and relationships.
Builds a semantic model describing symbols and relationships.
Back-end:
## Back-end:
Renders documentation using interchangeable renderers.
Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation.
---
## Rendering pipeline
# Rendering pipeline
Typical flow:
@@ -95,44 +112,6 @@ Typical flow:
---
## 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 by doc-forge and AI tooling.
@@ -148,299 +127,12 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Indent section contents using four spaces.
- Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form.
- Sections are separated by ```---```
---
## Package docstrings
- Package docstrings act as the documentation home page.
Recommended sections:
## Summary
## Installation
## Quick start
## Core concepts
## Architecture
## Rendering pipeline
## CLI usage
## Public API
## Examples
## Notes
Example:
Package Doc String:
'''
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
pip install foo-bar
---
# Quick start
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
---
# Public API
Foo
Bar
BarEngine
---
'''
---
## Module docstrings
- Module docstrings describe a subsystem.
Recommended sections:
## Summary
## Examples
## Notes
## Public API
Example:
Module Doc String:
'''
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
---
'''
---
## Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
foo = Foo("example", value=42)
print(foo.name)
'''
Complex Bar:
class BarEngine:
'''
Executes Foo objects through Bar stages.
Attributes:
foos (tuple[Foo, ...]):
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
'''
---
## Function and method docstrings
- Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
'''
Multiple Examples:
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
'''
Combine two Foo instances.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
Pipeline usage:
engine = BarEngine([foo1, foo2])
engine.run()
'''
---
## Property docstrings
- Properties must document return values.
Example:
Property Doc String:
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
container = FooContainer()
foos = container.foos
'''
---
## Attribute documentation
- Document attributes in class docstrings using Attributes:.
Example:
Attribute Doc String:
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
---
## Notes subsection grouping
- Group related information using labeled subsections.
@@ -467,26 +159,33 @@ Example:
## Example formatting
- Use indentation for examples.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
@@ -495,8 +194,9 @@ Avoid fenced code blocks inside structured sections.
## Separator rules
Use horizontal separators only at docstring root level to separate sections:
---
```markdown
---
```
Allowed locations:
@@ -508,6 +208,312 @@ Do not use separators inside code sections.
---
## Package docstrings
- Package docstrings act as the documentation home page.
Recommended sections:
# Summary
# Installation
# Quick start
# CLI usage
# Core concepts
# Architecture
# Rendering pipeline
# Examples
# Notes
Example:
Package Doc String:
'''
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
```bash
pip install foo-bar
```
---
# Quick start
```python
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
```
---
'''
---
## Module docstrings
- Module docstrings describe a subsystem.
Recommended sections:
# Summary
# Examples
# Notes
Example:
Module Doc String:
'''
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
```python
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
```
---
'''
---
## Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
```python
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
```python
foo = Foo("example", value=42)
print(foo.name)
```
'''
```
Complex Bar:
```python
class BarEngine:
'''
Executes Foo objects through Bar stages.
Attributes:
foos (tuple[Foo, ...]):
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
```python
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
## Function and method docstrings
- Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
```python
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
```
'''
```
Multiple Examples:
```python
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
'''
Combine two Foo instances.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
```python
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
```
Pipeline usage:
```python
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
## Property docstrings
- Properties must document return values.
Example:
Property Doc String:
```python
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
```python
container = FooContainer()
foos = container.foos
```
'''
```
---
## Attribute documentation
- Document attributes in class docstrings using Attributes:.
Example:
Attribute Doc String:
```python
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
```
---
## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract:

2
mcp_docs/modules/docforge.json
View File

File diff suppressed because one or more lines are too long