fixes for bland looking doc strings

docforge/__init__.py

@@ -5,7 +5,6 @@ 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
@@ -30,7 +29,6 @@ Example:
 ```python
 from my_package.foo import Bar
 ```
-
 ---
 
 ## Docstring Writing Standard
@@ -39,7 +37,6 @@ 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
@@ -49,44 +46,46 @@ package after reading only this docstring.
 
 Example:
 
-```python
 '''
-my_package
-
 Short description of what this package provides.
 
 ## Installation
 
+```bash
 pip install my-package
+```
 
 ## Quick start
 
+```python
 from my_package.foo import Bar
 
 bar = Bar()
 result = bar.process("example")
+```
+---
 
 ## 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
 
 1. Import public objects
 2. Initialize objects
 3. Call methods
+---
 
 ## Public API
 
 foo.Bar
 foo.helper_function
 '''
-```
-
 ---
 
 ## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
@@ -95,21 +94,18 @@ Explains a specific subsystem.
 
 Example:
 
-```python
 '''
-foo subsystem.
-
 Provides core functionality.
 
 ## Usage
 
+```python
 from my_package.foo import Bar
 
 bar = Bar()
 bar.process("example")
-'''
 ```
-
+'''
 ---
 
 ## Class docstring — Object contract
@@ -133,7 +129,6 @@ Include:
 * Lifecycle expectations
 * Thread safety (if relevant)
 * Performance characteristics (if relevant)
-
 ---
 
 ## Function and method docstrings — API specification
@@ -145,19 +140,25 @@ def process(self, value: str) -> str:
     '''
     Process an input value.
 
-    Args:
-        value:
-            Input string.
+    Parameters
+    ----------
+    value : str
+        value to be processed
+        Example:
+            'string'
 
-    Returns:
-        Processed string.
+    Returns
+    -------
+    processed value : str
+        result after processing value
+    ---
 
-    Raises:
-        ValueError:
-            If the input is invalid.
+    Behavior
+    --------
+    - behaviour 1
+    - behaviour 2
     '''
 ```
-
 ---
 
 ## Attribute docstrings (optional)
@@ -165,10 +166,27 @@ def process(self, value: str) -> str:
 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
@@ -176,6 +194,8 @@ self.name: str
 **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,12 +205,11 @@ self.name: str
 * Plain-text separators like `====`
 * Duplicate external documentation
 * Informal or conversational language
-
 ---
 
 ## How doc-forge uses these docstrings
 
-Build MkDocs site:
+### Build MkDocs site:
 
 ```bash
 doc-forge build --mkdocs --module my_package