fixes for broken Examples and other formatting issues

docforge/__init__.py

@@ -21,14 +21,6 @@ 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
@@ -46,46 +38,47 @@ package after reading only this docstring.
 
 Example:
 
-'''
-Short description of what this package provides.
+    '''
+    Short description of what this package provides.
 
-## Installation
+    ## Installation
 
-```bash
-pip install my-package
-```
+    ```bash
+    pip install my-package
+    ```
 
-## Quick start
+    ## Quick start
 
-```python
-from my_package.foo import Bar
+    ```python
+    from my_package.foo import Bar
 
-bar = Bar()
-result = bar.process("example")
-```
----
+    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
----
+    1. Import public objects
+    2. Initialize objects
+    3. Call methods
+    ---
 
-## Public API
+    ## Public API
 
-foo.Bar
-foo.helper_function
-'''
+    foo.Bar
+    foo.helper_function
+    ---
+    '''
 ---
 
 ## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
@@ -94,18 +87,19 @@ Explains a specific subsystem.
 
 Example:
 
-'''
-Provides core functionality.
+    '''
+    Provides core functionality.
 
-## Usage
+    ## Usage
 
-```python
-from my_package.foo import Bar
+    ```python
+    from my_package.foo import Bar
 
-bar = Bar()
-bar.process("example")
-```
-'''
+    bar = Bar()
+    bar.process("example")
+    ```
+    ---
+    '''
 ---
 
 ## Class docstring — Object contract
@@ -120,6 +114,7 @@ class Bar:
     Performs processing on input data.
 
     Instances may be reused across multiple calls.
+    ---
     '''
 ```
 
@@ -136,17 +131,38 @@ Include:
 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.
+    ---
 
     Parameters
     ----------
-    value : str
+    value1 : str
+        required: True
         value to be processed
         Example:
             'string'
 
+    value2 : str
+        required: False
+        default: "default value"
+        value to be processed
+        Example:
+            'string'
+
+    value3 : str
+        required: False
+        value to be processed
+        Example:
+            'string'
+    ---
+
     Returns
     -------
     processed value : str
@@ -157,6 +173,7 @@ def process(self, value: str) -> str:
     --------
     - behaviour 1
     - behaviour 2
+    ---
     '''
 ```
 ---
@@ -215,13 +232,14 @@ class Class
 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