diff --git a/docforge/__init__.py b/docforge/__init__.py index 8db5b5d..3a2ad42 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -1,270 +1,435 @@ """ -Renderer-agnostic Python documentation compiler that converts docstrings into -structured documentation for both humans (MkDocs) and machines (MCP / AI agents). +Renderer-agnostic Python documentation compiler that converts Python docstrings +into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). + +`doc-forge` statically analyzes source code, builds a semantic model of modules, +classes, functions, and attributes, and renders that model into documentation +outputs without executing user code. -`doc-forge` statically analyzes your source code, builds a semantic model of -modules and objects, and renders that model into documentation outputs without -executing your code. --- -# Core Philosophy +## Installation + +Install using pip: + + pip install doc-forge + +--- + +## Quick start + +Generate a MkDocs site from a Python package: + + doc-forge build --mkdocs --module my_package + +Generate MCP JSON documentation: + + doc-forge build --mcp --module my_package + +Serve documentation locally: + + doc-forge serve --mkdocs --module my_package + +--- + +## Core concepts + +**Loader** + +Extracts symbols, signatures, and docstrings using static analysis. + +**Semantic model** + +Structured, renderer-agnostic representation of the API. + +**Renderer** + +Converts the semantic model into output formats such as MkDocs or MCP JSON. + +**Symbol** + +Any documentable object: + + - module + - class + - function + - method + - property + - attribute + +--- + +## Architecture `doc-forge` follows a compiler architecture: -1. **Front-end (Introspection)** - Static analysis of modules, classes, functions, signatures, and docstrings. +Front-end: -2. **Middle-end (Semantic Model)** - Renderer-neutral structured representation of your API. + Static analysis of modules, classes, functions, type hints, and docstrings. -3. **Back-end (Renderers)** +Middle-end: + + Builds a semantic model describing symbols and relationships. + +Back-end: + + Renders documentation using interchangeable renderers. + +This architecture ensures deterministic documentation generation. - * MkDocs → human documentation - * MCP JSON → AI-readable documentation --- -# Docstring Writing Standard +## Rendering pipeline -Docstrings are the single source of truth. `doc-forge` does not generate content. -It compiles and renders what you write. +Typical flow: + + Python package + ↓ + Loader (static analysis) + ↓ + Semantic model + ↓ + Renderer + ↓ + MkDocs site or MCP JSON + +--- + +## 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. + +Docstrings are the single source of truth. doc-forge compiles docstrings but does +not generate documentation content. Documentation follows the Python import hierarchy. + --- -# Package docstring (`package/__init__.py`) — Full user guide +### General rules -This is the landing page. A developer must be able to install and use the -package after reading only this docstring. +Use Markdown headings at package and module level. -## Example: +Use Google-style sections at class and function level. - ''' - Short description of what this package provides. +Supported structured sections: - # Installation + Args: + Returns: + Raises: + Yields: + Attributes: + Notes: + Example: + Examples: + See Also: - ```bash - pip install my-package - ``` +Indent section contents using four spaces. - # Quick start +Type information must come from function signatures, not duplicated prose. - ```python - from my_package.foo import Bar - - bar = Bar() - result = bar.process("example") - ``` - --- - - # Core concepts - - ## Bar - - Primary object exposed by the package. - - ## foo module - - Provides core functionality. - --- - - # Typical workflow - - 1. Import public objects - 2. Initialize objects - 3. Call methods - --- - - # Public API - - foo.Bar - foo.helper_function - --- - ''' ---- - -# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide - -Explains a specific subsystem. - -## Example: - - ''' - Provides core functionality. - - # Usage - - ```python - from my_package.foo import Bar - - bar = Bar() - bar.process("example") - ``` - --- - ''' ---- - -# Class docstring — Object contract - -Defines responsibility and behavior. - -## Example: - -```python -class Bar: - ''' - Performs processing on input data. - - Instances may be reused across multiple calls. - --- - ''' -``` - -Include: - -* Responsibility -* Lifecycle expectations -* Thread safety (if relevant) -* Performance characteristics (if relevant) ---- - -# Function and method docstrings — API specification - -## Example: - -```python -def process( - self, - value1: str, - value2: str | None = "default value", - value3: str | None = None, -) -> str: - ''' - Process an input value. - --- +Avoid NumPy-style sections such as: Parameters - ---------- - value1 : str - required: True - value to be processed - Example: - 'string' + Returns tables - value2 : str - required: False - default: "default value" - value to be processed - Example: - 'string' +Avoid pseudo-fields such as: + + required: + default: + +--- + +### Package docstrings + +Package docstrings act as the documentation home page. + +They should include: + + Summary + --- + Installation + Quick start + Core concepts + Architecture + Rendering pipeline + CLI usage + Public API + Examples + Notes + +Example: + + ''' + My package summary. - value3 : str - required: False - value to be processed - Example: - 'string' --- - Returns - ------- - processed value : str - result after processing value + ## Installation + + pip install my-package + + ## Quick start + + from my_package import Foo + + foo = Foo() + foo.run() + ''' + +--- + +### Module docstrings + +Module docstrings describe subsystems. + +Recommended sections: + + Summary + --- + Examples + Notes + Public API + +Example: + + ''' + Execution subsystem. + --- - Behavior - -------- - - behaviour 1 - - behaviour 2 + Example: + + from my_package.engine import Engine + + engine = Engine(nodes) + ''' + +--- + +### Class docstrings + +Class docstrings define object responsibility and lifecycle. + +Supported sections: + + Attributes: + Notes: + Example: + Raises: + +Example: + + class Engine: + ''' + Executes pipelines. + + Attributes: + nodes (tuple[Node, ...]): + Execution nodes. + + Notes: + Guarantees: + + - deterministic execution + - immutable state propagation + + Lifecycle: + + - reusable across executions + + Example: + Basic usage: + + engine = Engine(nodes) + engine.run(state) + ''' + +--- + +### Function and method docstrings + +Function docstrings define API contracts. + +Supported sections: + + Args: + Returns: + Raises: + Yields: + Notes: + Example: + +Example: + + def run(state: State) -> list[State]: + ''' + Execute pipeline. + + Args: + state (State): + Initial execution state. + + Returns: + list[State]: + Resulting execution states. + + Notes: + Guarantees: + + - state is not modified + ''' + +--- + +### Property docstrings + +Properties must document return values. + +Example: + + @property + def nodes(self) -> tuple[Node, ...]: + ''' + Return execution nodes. + + Returns: + tuple[Node, ...]: + Configured nodes. + ''' + +--- + +### Attribute documentation + +Attributes must be documented in the class docstring using Attributes:. + +Example: + + class State: + ''' + Execution state. + + Attributes: + payload (dict): + Immutable execution data. + + depth (int): + Distance from root state. + ''' + +--- + +### Notes subsection grouping + +Subsections may be grouped using labeled blocks: + + Notes: + Guarantees: + + - deterministic execution + + Lifecycle: + + - reusable instance + + Thread safety: + + - safe for concurrent use + +Do not use horizontal separators inside structured sections. + +--- + +### Example formatting + +Use indentation for examples: + + Example: + Basic usage: + + engine = Engine(nodes) + engine.run(state) + +Multiple examples may be grouped using labels. + +--- + +### Separator rules + +Use horizontal separators only at docstring root level: + --- - ''' -``` + +Do not use separators inside: + + Args: + Returns: + Notes: + Attributes: + --- -# Attribute docstrings (optional) +### Parsing guarantees -## Example: +GSDFC ensures doc-forge can deterministically extract: -```python -class Class - ''' - attribute1 : str - required: True - default: "default value" - attribute description + symbol type + symbol name + parameters + return types + attributes + examples + structured notes - attribute2 : str - required: False - attribute description +This enables reliable MkDocs rendering and MCP export. - attribute2 : str - required: False - default: "default value" - attribute description - ''' - - attribute1: str = "default value" - attribute2: str | None = None - attribute3: str | None = "default value" -``` --- -# Writing Rules +## Notes -**Heading hierarchy** +doc-forge never executes analyzed modules. -Module docstring - -- Examples -- Usage -- Core concepts -- Public API - -Class docstring - -- Attributes -- Execution contract -- Lifecycle -- Thread safety -- Notes - -Method docstring - -- Parameters -- Returns -- Raises -- Yields -- Behavior - -**Required** - -* Use Markdown headings -* Use Markdown line separator `---` -* Line separator should be followed by a blank line -* Provide real import examples -* Document all public APIs -* Keep descriptions precise and factual - -**Avoid** - -* Plain-text separators like `====` -* Duplicate external documentation -* Informal or conversational language ---- - -# How doc-forge uses these docstrings - -## Build MkDocs site: - -```bash -doc-forge build --mkdocs --module my_package -``` - -## Build MCP documentation: - -```bash -doc-forge build --mcp --module my_package -``` - -Both outputs are generated directly from docstrings. ---- +Documentation is generated entirely through static analysis. """ from .loaders import GriffeLoader, discover_module_paths