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