google styled doc string

docforge/__init__.py

@@ -1,86 +1,536 @@
 """
-# doc-forge
+Renderer-agnostic Python documentation compiler that converts Python docstrings
+into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
 
-`doc-forge` is a renderer-agnostic Python documentation compiler designed for
-speed, flexibility, and beautiful output. It decouples the introspection of
-your code from the rendering process, allowing you to generate documentation
-for various platforms (starting with MkDocs) from a single internal models.
+`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.
 
-## Core Philosophy
-
-`doc-forge` operates on two fundamental principles:
-
-1.  **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.
-2.  **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
-    -   **Front-end (Introspection)**: Static analysis of source code and docstrings.
-    -   **Middle-end (Semantic Model)**: A renderer-neutral internal representation.
-    -   **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.
-
-## Documentation Design
-
-`doc-forge` is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
-
-### For Humans (Readability & Structure)
-- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.
-- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
-- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.
-
-### For LLMs (AI-Native Knowledge)
-- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
-- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
-- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.
-## Available Commands
-
-- **build**: Build documentation (MkDocs site or MCP resources).
-- **serve**: Serve documentation (MkDocs or MCP).
-- **tree**: Visualize the introspected project structure.
+---
 
 ## Installation
 
-Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
+Install using pip:
 
-```bash
     pip install doc-forge
-```
 
-## Quick Start
+---
 
-1.  **Build Documentation**:
-    Introspect your package and generate documentation in one step:
-    ```bash
-    # Build MkDocs site
-    doc-forge build --mkdocs --module my_package --site-name "My Docs"
+## Quick start
+
+Generate a MkDocs site from a Python package:
+
+    doc-forge build --mkdocs --module my_package
+
+Generate MCP JSON documentation:
 
-    # Build MCP resources
     doc-forge build --mcp --module my_package
-    ```
 
-2.  **Define Navigation**:
-    Create a `docforge.nav.yml` to organize your documentation:
-    ```yaml
-    home: my_package/index.md
-    groups:
-      Core API:
-        - my_package/core/*.md
-      Utilities:
-        - my_package/utils.md
-    ```
+Serve documentation locally:
 
-3.  **Preview**:
-    ```bash
-    # Serve MkDocs site
-    doc-forge serve --mkdocs
+    doc-forge serve --mkdocs --module my_package
 
-    # Serve MCP documentation
-    doc-forge serve --mcp
-    ```
+---
 
-## Project Structure
+## Core concepts
 
-- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
-- `docforge.models`: The internal representation of your project, modules, and objects.
-- `docforge.renderers`: Converters that turn the models into physical files.
-- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
+**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.
 """
 
 from .loaders import GriffeLoader, discover_module_paths

docforge/templates/mkdocs.sample.yml

@@ -31,3 +31,8 @@ plugins:
             annotations_path: brief
             show_root_heading: true
             group_by_category: true
+
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true

mcp_docs/modules/docforge.json

@@ -2,7 +2,7 @@
   "module": "docforge",
   "content": {
     "path": "docforge",
-    "docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Core Philosophy\n\n`doc-forge` operates on two fundamental principles:\n\n1.  **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.\n2.  **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:\n    -   **Front-end (Introspection)**: Static analysis of source code and docstrings.\n    -   **Middle-end (Semantic Model)**: A renderer-neutral internal representation.\n    -   **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.\n\n## Documentation Design\n\n`doc-forge` is an \"AI-Native\" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:\n\n### For Humans (Readability & Structure)\n- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.\n- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.\n- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.\n\n### For LLMs (AI-Native Knowledge)\n- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to \"understand\" your API surface area without layout noise.\n- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.\n- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1.  **Build Documentation**:\n    Introspect your package and generate documentation in one step:\n    ```bash\n    # Build MkDocs site\n    doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n    # Build MCP resources\n    doc-forge build --mcp --module my_package\n    ```\n\n2.  **Define Navigation**:\n    Create a `docforge.nav.yml` to organize your documentation:\n    ```yaml\n    home: my_package/index.md\n    groups:\n      Core API:\n        - my_package/core/*.md\n      Utilities:\n        - my_package/utils.md\n    ```\n\n3.  **Preview**:\n    ```bash\n    # Serve MkDocs site\n    doc-forge serve --mkdocs\n\n    # Serve MCP documentation\n    doc-forge serve --mcp\n    ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.",
+    "docstring": "Renderer-agnostic Python documentation compiler that converts docstrings into\nstructured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes your source code, builds a semantic model of\nmodules and objects, and renders that model into documentation outputs without\nexecuting your code.\n---\n\n# Core Philosophy\n\n`doc-forge` follows a compiler architecture:\n\n1. **Front-end (Introspection)**\n   Static analysis of modules, classes, functions, signatures, and docstrings.\n\n2. **Middle-end (Semantic Model)**\n   Renderer-neutral structured representation of your API.\n\n3. **Back-end (Renderers)**\n\n   * MkDocs → human documentation\n   * MCP JSON → AI-readable documentation\n---\n\n# Docstring Writing Standard\n\nDocstrings are the single source of truth. `doc-forge` does not generate content.\nIt compiles and renders what you write.\n\nDocumentation follows the Python import hierarchy.\n---\n\n# Package docstring (`package/__init__.py`) — Full user guide\n\nThis is the landing page. A developer must be able to install and use the\npackage after reading only this docstring.\n\n## Example:\n\n    '''\n    Short description of what this package provides.\n\n    # Installation\n\n    ```bash\n    pip install my-package\n    ```\n\n    # Quick start\n\n    ```python\n    from my_package.foo import Bar\n\n    bar = Bar()\n    result = bar.process(\"example\")\n    ```\n    ---\n\n    # Core concepts\n\n    ## Bar\n    - Primary object exposed by the package.\n\n    ## foo module\n    - Provides core functionality.\n    ---\n\n    # Typical workflow\n\n    1. Import public objects\n    2. Initialize objects\n    3. Call methods\n    ---\n\n    # Public API\n\n    foo.Bar\n    foo.helper_function\n    ---\n    '''\n---\n\n# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\n## Example:\n\n    '''\n    Provides core functionality.\n\n    # Usage\n\n    ```python\n    from my_package.foo import Bar\n\n    bar = Bar()\n    bar.process(\"example\")\n    ```\n    ---\n    '''\n---\n\n# Class docstring — Object contract\n\nDefines responsibility and behavior.\n\n## Example:\n\n```python\nclass Bar:\n    '''\n    Performs processing on input data.\n\n    Instances may be reused across multiple calls.\n    ---\n    '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n---\n\n# Function and method docstrings — API specification\n\n## Example:\n\n```python\ndef process(\n    self,\n    value1: str,\n    value2: str | None = \"default value\",\n    value3: str | None = None,\n) -> str:\n    '''\n    Process an input value.\n    ---\n\n    Parameters\n    ----------\n    value1 : str\n        required: True\n        value to be processed\n        Example:\n            'string'\n\n    value2 : str\n        required: False\n        default: \"default value\"\n        value to be processed\n        Example:\n            'string'\n\n    value3 : str\n        required: False\n        value to be processed\n        Example:\n            'string'\n    ---\n\n    Returns\n    -------\n    processed value : str\n        result after processing value\n    ---\n\n    Behavior\n    --------\n    - behaviour 1\n    - behaviour 2\n    ---\n    '''\n```\n---\n\n# Attribute docstrings (optional)\n\n## Example:\n\n```python\nclass Class\n    '''\n    attribute1 : str\n        required: True\n        default: \"default value\"\n        attribute description\n\n    attribute2 : str\n        required: False\n        attribute description\n\n    attribute2 : str\n        required: False\n        default: \"default value\"\n        attribute description\n    '''\n\n    attribute1: str = \"default value\"\n    attribute2: str | None = None\n    attribute3: str | None = \"default value\"\n```\n---\n\n# Writing Rules\n\n**Heading hierarchy**\n\nModule docstring\n\n- Examples\n- Usage\n- Core concepts\n- Public API\n\nClass docstring\n\n- Attributes\n- Execution contract\n- Lifecycle\n- Thread safety\n- Notes\n\nMethod docstring\n\n- Parameters\n- Returns\n- Raises\n- Yields\n- Behavior\n\n**Required**\n\n* Use Markdown headings\n* Use Markdown line separator `---`\n* Line separator should be followed by a blank line\n* Provide real import examples\n* Document all public APIs\n* Keep descriptions precise and factual\n\n**Avoid**\n\n* Plain-text separators like `====`\n* Duplicate external documentation\n* Informal or conversational language\n---\n\n# How doc-forge uses these docstrings\n\n## Build MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.\n---",
     "objects": {
       "GriffeLoader": {
         "name": "GriffeLoader",

mkdocs.yml

@@ -31,6 +31,10 @@ plugins:
           annotations_path: brief
           show_root_heading: true
           group_by_category: true
+markdown_extensions:
+- pymdownx.superfences
+- pymdownx.tabbed:
+    alternate_style: true
 site_name: docforge
 nav:
 - Home: index.md