updated docs strings and added README.md

docforge/__init__.py

@@ -1,4 +1,6 @@
 """
+# Summary
+
 Renderer-agnostic Python documentation compiler that converts Python docstrings
 into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
 
@@ -101,13 +103,13 @@ This architecture ensures deterministic documentation generation.
 Typical flow:
 
     Python package
-        ↓
+        |
     Loader (static analysis)
-        ↓
+        |
     Semantic model
-        ↓
+        |
     Renderer
-        ↓
+        |
     MkDocs site or MCP JSON
 
 ---
@@ -117,7 +119,7 @@ Typical flow:
 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.
+- `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.
 
@@ -129,34 +131,33 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
 - Use **Google-style structured sections** at class, function, and method level.
 - Use type hints in signatures instead of duplicating types in prose.
 - Write summaries in imperative form.
-- Sections are separated by ```---```
+- Sections are separated by `---`
 
 ---
 
-## Notes subsection grouping
+# Notes subsection grouping
 
-- Group related information using labeled subsections.
+Group related information using labeled subsections.
 
 Example:
-    Notes Example:
 
-        Notes:
-            **Guarantees:**
+    Notes:
+        **Guarantees:**
 
-                - deterministic behavior
+            - deterministic behavior
 
-            **Lifecycle:**
+        **Lifecycle:**
 
-                - created during initialization
-                - reused across executions
+            - created during initialization
+            - reused across executions
 
-            **Thread safety:**
+        **Thread safety:**
 
-                - safe for concurrent reads
+            - safe for concurrent reads
 
 ---
 
-## Example formatting
+# Example formatting
 
 - Use indentation for examples.
 - Indent section contents using four spaces.
@@ -192,9 +193,10 @@ Avoid fenced code blocks inside structured sections.
 
 ---
 
-## Separator rules
+# Separator rules
 
 Use horizontal separators only at docstring root level to separate sections:
+
 ```markdown
 ---
 ```
@@ -209,9 +211,9 @@ Do not use separators inside code sections.
 
 ---
 
-## Package docstrings
+# Package docstrings
 
-- Package docstrings act as the documentation home page.
+Package docstrings act as the documentation home page.
 
 Recommended sections:
 
@@ -229,6 +231,8 @@ Example:
     Package Doc String:
 
         '''
+        # Summary
+
         Foo-bar processing framework.
 
         Provides tools for defining Foo objects and executing Bar pipelines.
@@ -259,9 +263,9 @@ Example:
 
 ---
 
-## Module docstrings
+# Module docstrings
 
-- Module docstrings describe a subsystem.
+Module docstrings describe a subsystem.
 
 Recommended sections:
 
@@ -273,6 +277,8 @@ Example:
     Module Doc String:
 
         '''
+        # Summary
+
         Foo execution subsystem.
 
         Provides utilities for executing Foo objects through Bar stages.
@@ -296,9 +302,9 @@ Example:
 
 ---
 
-## Class docstrings
+# Class docstrings
 
-- Class docstrings define object responsibility, lifecycle, and attributes.
+Class docstrings define object responsibility, lifecycle, and attributes.
 
 Recommended sections:
 
@@ -373,9 +379,9 @@ Example:
 
 ---
 
-## Function and method docstrings
+# Function and method docstrings
 
-- Function docstrings define API contracts.
+Function docstrings define API contracts.
 
 Recommended sections:
 
@@ -465,9 +471,9 @@ Example:
 
 ---
 
-## Property docstrings
+# Property docstrings
 
-- Properties must document return values.
+Properties must document return values.
 
 Example:
     Property Doc String:
@@ -493,9 +499,9 @@ Example:
 
 ---
 
-## Attribute documentation
+# Attribute documentation
 
-- Document attributes in class docstrings using Attributes:.
+Document attributes in class docstrings using `Attributes:`.
 
 Example:
     Attribute Doc String:
@@ -515,7 +521,7 @@ Example:
 
 ---
 
-## Parsing guarantees
+# Parsing guarantees
 
 GSDFC ensures doc-forge can deterministically extract: