added hierarchy rules

docforge/__init__.py

@@ -5,10 +5,9 @@ structured documentation for both humans (MkDocs) and machines (MCP / AI agents)
 `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
+# Core Philosophy
 
 `doc-forge` follows a compiler architecture:
 
@@ -22,101 +21,92 @@ executing your code.
 
    * MkDocs → human documentation
    * MCP JSON → AI-readable documentation
-
-The atomic unit of documentation is the Python import path.
-
-Example:
-
-```python
-from my_package.foo import Bar
-```
-
 ---
 
-## Docstring Writing Standard
+# 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
+# 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:
+## Example:
 
-```python
     '''
-my_package
-
     Short description of what this package provides.
 
-## Installation
+    # Installation
 
+    ```bash
     pip install my-package
+    ```
 
-## Quick start
+    # Quick start
 
+    ```python
     from my_package.foo import Bar
 
     bar = Bar()
     result = bar.process("example")
+    ```
+    ---
 
-## Core concepts
+    # Core concepts
 
-Bar
-    Primary object exposed by the package.
+    ## Bar
+    - Primary object exposed by the package.
 
-foo module
-    Provides core functionality.
+    ## foo module
+    - Provides core functionality.
+    ---
 
-## Typical workflow
+    # Typical workflow
 
     1. Import public objects
     2. Initialize objects
     3. Call methods
+    ---
 
-## Public API
+    # Public API
 
     foo.Bar
     foo.helper_function
+    ---
     '''
-```
-
 ---
 
-## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
+# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
 
 Explains a specific subsystem.
 
-Example:
+## Example:
 
-```python
     '''
-foo subsystem.
-
     Provides core functionality.
 
-## Usage
+    # Usage
 
+    ```python
     from my_package.foo import Bar
 
     bar = Bar()
     bar.process("example")
-'''
     ```
-
+    ---
+    '''
 ---
 
-## Class docstring — Object contract
+# Class docstring — Object contract
 
 Defines responsibility and behavior.
 
-Example:
+## Example:
 
 ```python
 class Bar:
@@ -124,6 +114,7 @@ class Bar:
     Performs processing on input data.
 
     Instances may be reused across multiple calls.
+    ---
     '''
 ```
 
@@ -133,49 +124,120 @@ Include:
 * Lifecycle expectations
 * Thread safety (if relevant)
 * Performance characteristics (if relevant)
-
 ---
 
-## Function and method docstrings — API specification
+# Function and method docstrings — API specification
 
-Example:
+## Example:
 
 ```python
-def process(self, value: str) -> str:
+def process(
+    self,
+    value1: str,
+    value2: str | None = "default value",
+    value3: str | None = None,
+) -> str:
     '''
     Process an input value.
+    ---
 
-    Args:
-        value:
-            Input string.
+    Parameters
+    ----------
+    value1 : str
+        required: True
+        value to be processed
+        Example:
+            'string'
 
-    Returns:
-        Processed string.
+    value2 : str
+        required: False
+        default: "default value"
+        value to be processed
+        Example:
+            'string'
 
-    Raises:
-        ValueError:
-            If the input is invalid.
+    value3 : str
+        required: False
+        value to be processed
+        Example:
+            'string'
+    ---
+
+    Returns
+    -------
+    processed value : str
+        result after processing value
+    ---
+
+    Behavior
+    --------
+    - behaviour 1
+    - behaviour 2
+    ---
     '''
 ```
-
 ---
 
-## Attribute docstrings (optional)
+# Attribute docstrings (optional)
 
-Example:
+## Example:
 
 ```python
-self.name: str
-'''Identifier used during processing.'''
-```
+class Class
+    '''
+    attribute1 : str
+        required: True
+        default: "default value"
+        attribute description
 
+    attribute2 : str
+        required: False
+        attribute description
+
+    attribute2 : str
+        required: False
+        default: "default value"
+        attribute description
+    '''
+
+    attribute1: str = "default value"
+    attribute2: str | None = None
+    attribute3: str | None = "default value"
+```
 ---
 
-## Writing Rules
+# Writing Rules
+
+**Heading hierarchy**
+
+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
@@ -185,24 +247,24 @@ self.name: str
 * Plain-text separators like `====`
 * Duplicate external documentation
 * Informal or conversational language
-
 ---
 
-## How doc-forge uses these docstrings
+# How doc-forge uses these docstrings
 
-Build MkDocs site:
+## Build MkDocs site:
 
 ```bash
 doc-forge build --mkdocs --module my_package
 ```
 
-Build MCP documentation:
+## Build MCP documentation:
 
 ```bash
 doc-forge build --mcp --module my_package
 ```
 
 Both outputs are generated directly from docstrings.
+---
 """
 
 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": "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.",
+    "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