diff --git a/docforge/__init__.py b/docforge/__init__.py index 3a2ad42..eb1b272 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -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 ---