doc string changes with sample to generate doc strings for packages/modules

docforge/__init__.py

@@ -1,86 +1,208 @@
 """
-# doc-forge
+Renderer-agnostic Python documentation compiler that converts docstrings into
+structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
 
-`doc-forge` is a renderer-agnostic Python documentation compiler designed for
+`doc-forge` statically analyzes your source code, builds a semantic model of
-speed, flexibility, and beautiful output. It decouples the introspection of
+modules and objects, and renders that model into documentation outputs without
-your code from the rendering process, allowing you to generate documentation
+executing your code.
-for various platforms (starting with MkDocs) from a single internal models.
+
+---
 
 ## Core Philosophy
 
-`doc-forge` operates on two fundamental principles:
+`doc-forge` follows a compiler architecture:
 
-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.
+1. **Front-end (Introspection)**
-2.  **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
+   Static analysis of modules, classes, functions, signatures, and docstrings.
-    -   **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
+2. **Middle-end (Semantic Model)**
+   Renderer-neutral structured representation of your API.
 
-`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:
+3. **Back-end (Renderers)**
 
-### For Humans (Readability & Structure)
+   * MkDocs → human documentation
-- **`__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.
+   * MCP JSON → AI-readable documentation
-- **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)
+The atomic unit of documentation is the Python import path.
-- **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).
+Example:
-- **serve**: Serve documentation (MkDocs or MCP).
+
-- **tree**: Visualize the introspected project structure.
+```python
+from my_package.foo import Bar
+```
+
+---
+
+## Docstring Writing Standard
+
+Docstrings are the single source of truth. `doc-forge` does not generate content.
+It compiles and renders what you write.
+
+Documentation follows the Python import hierarchy.
+
+---
+
+## Package docstring (`package/__init__.py`) — Full user guide
+
+This is the landing page. A developer must be able to install and use the
+package after reading only this docstring.
+
+Example:
+
+```python
+'''
+my_package
+
+Short description of what this package provides.
 
 ## Installation
 
-Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
+pip install my-package
 
-```bash
+## Quick start
-pip install doc-forge
+
+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
+'''
 ```
 
-## Quick Start
+---
+
+## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
+
+Explains a specific subsystem.
+
+Example:
+
+```python
+'''
+foo subsystem.
+
+Provides core functionality.
+
+## Usage
+
+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, value: str) -> str:
+    '''
+    Process an input value.
+
+    Args:
+        value:
+            Input string.
+
+    Returns:
+        Processed string.
+
+    Raises:
+        ValueError:
+            If the input is invalid.
+    '''
+```
+
+---
+
+## Attribute docstrings (optional)
+
+Example:
+
+```python
+self.name: str
+'''Identifier used during processing.'''
+```
+
+---
+
+## Writing Rules
+
+**Required**
+
+* Use Markdown headings
+* 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:
 
-1.  **Build Documentation**:
-    Introspect your package and generate documentation in one step:
 ```bash
-    # Build MkDocs site
+doc-forge build --mkdocs --module my_package
-    doc-forge build --mkdocs --module my_package --site-name "My Docs"
+```
 
-    # Build MCP resources
+Build MCP documentation:
+
+```bash
 doc-forge build --mcp --module my_package
 ```
 
-2.  **Define Navigation**:
+Both outputs are generated directly from docstrings.
-    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
-    ```
-
-3.  **Preview**:
-    ```bash
-    # Serve MkDocs site
-    doc-forge serve --mkdocs
-
-    # Serve MCP documentation
-    doc-forge serve --mcp
-    ```
-
-## Project Structure
-
-- `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.
 """
 
 from .loaders import GriffeLoader, discover_module_paths

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\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\nThe atomic unit of documentation is the Python import path.\n\nExample:\n\n```python\nfrom my_package.foo import Bar\n```\n\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\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\nExample:\n\n```python\n'''\nmy_package\n\nShort description of what this package provides.\n\n## Installation\n\npip install my-package\n\n## Quick start\n\nfrom my_package.foo import Bar\n\nbar = Bar()\nresult = bar.process(\"example\")\n\n## Core concepts\n\nBar\n    Primary object exposed by the package.\n\nfoo module\n    Provides core functionality.\n\n## Typical workflow\n\n1. Import public objects\n2. Initialize objects\n3. Call methods\n\n## Public API\n\nfoo.Bar\nfoo.helper_function\n'''\n```\n\n---\n\n## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\nExample:\n\n```python\n'''\nfoo subsystem.\n\nProvides core functionality.\n\n## Usage\n\nfrom my_package.foo import Bar\n\nbar = Bar()\nbar.process(\"example\")\n'''\n```\n\n---\n\n## Class docstring — Object contract\n\nDefines responsibility and behavior.\n\nExample:\n\n```python\nclass Bar:\n    '''\n    Performs processing on input data.\n\n    Instances may be reused across multiple calls.\n    '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n\n---\n\n## Function and method docstrings — API specification\n\nExample:\n\n```python\ndef process(self, value: str) -> str:\n    '''\n    Process an input value.\n\n    Args:\n        value:\n            Input string.\n\n    Returns:\n        Processed string.\n\n    Raises:\n        ValueError:\n            If the input is invalid.\n    '''\n```\n\n---\n\n## Attribute docstrings (optional)\n\nExample:\n\n```python\nself.name: str\n'''Identifier used during processing.'''\n```\n\n---\n\n## Writing Rules\n\n**Required**\n\n* Use Markdown headings\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\n## How doc-forge uses these docstrings\n\nBuild MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\nBuild MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.",
     "objects": {
       "GriffeLoader": {
         "name": "GriffeLoader",