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 19:19:20 +05:30
parent 87a7f4eee1
commit 3f68e51e58
1 changed files with 253 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

401
docforge/__init__.py
View File

@@ -135,122 +135,122 @@ Models:
## Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs
and remain machine-parsable.
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
Docstrings are the single source of truth. doc-forge compiles docstrings but does
not generate documentation content.
Documentation follows the Python import hierarchy.
- Docstrings are the single source of truth.
- doc-forge compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring.
---
### General rules
Use Markdown headings at package and module level.
Use Google-style sections at class and function level.
Supported structured sections:
Args:
Returns:
Raises:
Yields:
Attributes:
Notes:
Example:
Examples:
See Also:
Indent section contents using four spaces.
Type information must come from function signatures, not duplicated prose.
Avoid NumPy-style sections such as:
Parameters
Returns tables
Avoid pseudo-fields such as:
required:
default:
- 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.
- Package docstrings act as the documentation home page.
They should include:
Recommended sections:
Summary
---
Installation
Quick start
Core concepts
Architecture
Rendering pipeline
CLI usage
Public API
Examples
Notes
## Summary
## Installation
## Quick start
## Core concepts
## Architecture
## Rendering pipeline
## CLI usage
## Public API
## Examples
## Notes
Example:
Package Doc String:
'''
My package summary.
'''
Foo-bar processing framework.
---
Provides tools for defining Foo objects and executing Bar pipelines.
## Installation
---
pip install my-package
## Installation
## Quick start
pip install foo-bar
from my_package import Foo
---
foo = Foo()
foo.run()
'''
## 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 subsystems.
- Module docstrings describe a subsystem.
Recommended sections:
Summary
---
Examples
Notes
Public API
## Summary
## Examples
## Notes
## Public API
Example:
Module Doc String:
'''
Execution subsystem.
'''
Foo execution subsystem.
---
Provides utilities for executing Foo objects through Bar stages.
Example:
---
from my_package.engine import Engine
Example:
engine = Engine(nodes)
'''
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 and lifecycle.
- Class docstrings define object responsibility, lifecycle, and attributes.
Supported sections:
Recommended sections:
Attributes:
Notes:
@@ -258,39 +258,68 @@ Supported sections:
Raises:
Example:
Simple Foo:
class Engine:
'''
Executes pipelines.
class Foo:
'''
Represents a unit of work.
Attributes:
nodes (tuple[Node, ...]):
Execution nodes.
Attributes:
name (str):
Identifier of the foo instance.
Notes:
Guarantees:
value (int):
Numeric value associated with foo.
- deterministic execution
- immutable state propagation
Notes:
Guarantees:
Lifecycle:
- instances are immutable after creation
- reusable across executions
Lifecycle:
Example:
Basic usage:
- create instance
- pass to processing engine
engine = Engine(nodes)
engine.run(state)
'''
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.
- Function docstrings define API contracts.
Supported sections:
Recommended sections:
Args:
Returns:
@@ -300,112 +329,184 @@ Supported sections:
Example:
Example:
Simple process method:
def run(state: State) -> list[State]:
'''
Execute pipeline.
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
state (State):
Initial execution state.
Args:
foo (Foo):
Foo instance to process.
Returns:
list[State]:
Resulting execution states.
multiplier (int):
Value used to scale foo.
Notes:
Guarantees:
Returns:
int:
Processed result.
- state is not modified
'''
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.
- Properties must document return values.
Example:
@property
def nodes(self) -> tuple[Node, ...]:
class FooContainer:
'''
Container for Foo objects.
'''
Return execution nodes.
Returns:
tuple[Node, ...]:
Configured nodes.
'''
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
container = FooContainer()
foos = container.foos
'''
---
### Attribute documentation
Attributes must be documented in the class docstring using Attributes:.
- Document attributes in class docstrings using Attributes:.
Example:
class State:
class Bar:
'''
Execution state.
Represents a processing stage.
Attributes:
payload (dict):
Immutable execution data.
id (str):
Unique identifier.
depth (int):
Distance from root state.
enabled (bool):
Whether the stage is active.
'''
---
### Notes subsection grouping
Subsections may be grouped using labeled blocks:
- Group related information using labeled subsections.
Example:
Notes:
Guarantees:
**Guarantees:**
- deterministic execution
- deterministic behavior
Lifecycle:
**Lifecycle:**
- reusable instance
- created during initialization
- reused across executions
Thread safety:
**Thread safety:**
- safe for concurrent use
Do not use horizontal separators inside structured sections.
- safe for concurrent reads
---
### Example formatting
Use indentation for examples:
- Use indentation for examples.
Single example:
Example:
Basic usage:
engine = Engine(nodes)
engine.run(state)
foo = Foo("example")
process(foo, multiplier=2)
Multiple examples may be grouped using labels.
Multiple examples:
Example:
Create foo:
foo = Foo("example")
Run engine:
engine = BarEngine([foo])
engine.run()
Avoid fenced code blocks inside structured sections.
---
### Separator rules
Use horizontal separators only at docstring root level:
Use horizontal separators only at docstring root level to separate sections:
---
Do not use separators inside:
Allowed locations:
Args:
Returns:
Notes:
Attributes:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
@@ -413,15 +514,19 @@ Do not use separators inside:
GSDFC ensures doc-forge can deterministically extract:
symbol type
symbol name
parameters
return types
attributes
examples
structured notes
- symbol kind (module, class, function, property, attribute)
- symbol name
- parameters
- return values
- attributes
- examples
- structured Notes subsections
This enables reliable MkDocs rendering and MCP export.
This enables:
- reliable MkDocs rendering
- deterministic MCP export
- accurate AI semantic interpretation
---