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

698
README.md
View File

@@ -9,47 +9,64 @@ outputs without executing user code.
--- ---
## Installation # Installation
Install using pip: Install using pip:
```bash
pip install doc-forge pip install doc-forge
```
--- ---
## Quick start # CLI usage
Generate a MkDocs site from a Python package: ## Generate an MkDocs site from a Python package:
```bash
doc-forge build --mkdocs --module my_package doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation: ## Generate MCP JSON documentation:
```bash
doc-forge build --mcp --module my_package doc-forge build --mcp --module my_package
```
Serve documentation locally:
## 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 doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
--- ---
## Core concepts # Core concepts
**Loader**
## Loader
Extracts symbols, signatures, and docstrings using static analysis. Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model** ## Semantic model
Structured, renderer-agnostic representation of the API. Structured, renderer-agnostic representation of the API.
**Renderer** ## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON. Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol** ## Symbol
Any documentable object
Any documentable object:
- module - module
- class - class
@@ -60,19 +77,19 @@ Any documentable object:
--- ---
## Architecture # Architecture
`doc-forge` follows a compiler 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.
@@ -80,7 +97,7 @@ This architecture ensures deterministic documentation generation.
--- ---
## Rendering pipeline # Rendering pipeline
Typical flow: 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) # 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. 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 **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method 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. - Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form. - Write summaries in imperative form.
- Sections are separated by ```---``` - 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 ## Notes subsection grouping
- Group related information using labeled subsections. - Group related information using labeled subsections.
@@ -468,26 +160,33 @@ Example:
## Example formatting ## Example formatting
- Use indentation for examples. - Use indentation for examples.
- Use code blocks for example code.
Example: Example:
Single example: Single example:
Example: Example:
```python
foo = Foo("example") foo = Foo("example")
process(foo, multiplier=2) process(foo, multiplier=2)
```
Multiple examples: Multiple examples:
Example: Example:
Create foo: Create foo:
```python
foo = Foo("example") foo = Foo("example")
```
Run engine: Run engine:
```python
engine = BarEngine([foo]) engine = BarEngine([foo])
engine.run() engine.run()
```
Avoid fenced code blocks inside structured sections. Avoid fenced code blocks inside structured sections.
@@ -496,8 +195,9 @@ Avoid fenced code blocks inside structured sections.
## Separator rules ## Separator rules
Use horizontal separators only at docstring root level to separate sections: Use horizontal separators only at docstring root level to separate sections:
```markdown
--- ---
```
Allowed locations: 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 ## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract: GSDFC ensures doc-forge can deterministically extract:

698
docforge/__init__.py
View File

@@ -8,47 +8,64 @@ outputs without executing user code.
--- ---
## Installation # Installation
Install using pip: Install using pip:
```bash
pip install doc-forge pip install doc-forge
```
--- ---
## Quick start # CLI usage
Generate a MkDocs site from a Python package: ## Generate an MkDocs site from a Python package:
```bash
doc-forge build --mkdocs --module my_package doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation: ## Generate MCP JSON documentation:
```bash
doc-forge build --mcp --module my_package doc-forge build --mcp --module my_package
```
Serve documentation locally:
## 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 doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
--- ---
## Core concepts # Core concepts
**Loader**
## Loader
Extracts symbols, signatures, and docstrings using static analysis. Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model** ## Semantic model
Structured, renderer-agnostic representation of the API. Structured, renderer-agnostic representation of the API.
**Renderer** ## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON. Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol** ## Symbol
Any documentable object
Any documentable object:
- module - module
- class - class
@@ -59,19 +76,19 @@ Any documentable object:
--- ---
## Architecture # Architecture
`doc-forge` follows a compiler 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.
@@ -79,7 +96,7 @@ This architecture ensures deterministic documentation generation.
--- ---
## Rendering pipeline # Rendering pipeline
Typical flow: 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) # 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. 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 **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method 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. - Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form. - Write summaries in imperative form.
- Sections are separated by ```---``` - 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 ## Notes subsection grouping
- Group related information using labeled subsections. - Group related information using labeled subsections.
@@ -467,26 +159,33 @@ Example:
## Example formatting ## Example formatting
- Use indentation for examples. - Use indentation for examples.
- Use code blocks for example code.
Example: Example:
Single example: Single example:
Example: Example:
```python
foo = Foo("example") foo = Foo("example")
process(foo, multiplier=2) process(foo, multiplier=2)
```
Multiple examples: Multiple examples:
Example: Example:
Create foo: Create foo:
```python
foo = Foo("example") foo = Foo("example")
```
Run engine: Run engine:
```python
engine = BarEngine([foo]) engine = BarEngine([foo])
engine.run() engine.run()
```
Avoid fenced code blocks inside structured sections. Avoid fenced code blocks inside structured sections.
@@ -495,8 +194,9 @@ Avoid fenced code blocks inside structured sections.
## Separator rules ## Separator rules
Use horizontal separators only at docstring root level to separate sections: Use horizontal separators only at docstring root level to separate sections:
```markdown
--- ---
```
Allowed locations: 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 ## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract: 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