doc-forge/README.md

# docforge

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.

---

## 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:

Front-end:

    Static analysis of modules, classes, functions, type hints, and docstrings.

Middle-end:

    Builds a semantic model describing symbols and relationships.

Back-end:

    Renders documentation using interchangeable renderers.

This architecture ensures deterministic documentation generation.

---

## Rendering pipeline

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 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.
- Every public symbol should have a complete and accurate docstring.

---

## General rules

- 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.

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

- Group related information using labeled subsections.

Example:
    Notes Example:

        Notes:
            **Guarantees:**

                - deterministic behavior

            **Lifecycle:**

                - created during initialization
                - reused across executions

            **Thread safety:**

                - safe for concurrent reads

---

## Example formatting

- Use indentation for examples.

Example:
    Single example:

        Example:

            foo = Foo("example")
            process(foo, multiplier=2)

    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 to separate sections:

    ---

Allowed locations:

- package docstrings
- module docstrings
- major documentation sections

Do not use separators inside code sections.

---

## Parsing guarantees

GSDFC ensures doc-forge can deterministically extract:

- symbol kind (module, class, function, property, attribute)
- symbol name
- parameters
- return values
- attributes
- examples
- structured Notes subsections

This enables:

- reliable MkDocs rendering
- deterministic MCP export
- accurate AI semantic interpretation

---

Notes:
    - doc-forge never executes analyzed modules.
    - Documentation is generated entirely through static analysis.