feat: add documentation generator README and enhance lazy import scanning to support _LAZY_GROUPS and TOOL_MAPPINGS patterns.

Author: MervinPraison

praisonai_tools/docs_generator/README.md

@@ -0,0 +1,86 @@
+# PraisonAI Docs Generator
+
+A powerful documentation generator for PraisonAI SDK reference documentation.
+
+## Installation
+
+```bash
+pip install praisonai-tools
+```
+
+## Quick Start
+
+### Using CLI
+
+```bash
+# Generate documentation with default settings
+praisonai-tools docs-generate
+
+# Generate with granular layout (separate pages for classes/functions)
+praisonai-tools docs-generate --layout granular
+
+# Specify custom output directory
+praisonai-tools docs-generate --output /path/to/docs
+```
+
+### Using Python Module
+
+```bash
+# Run as module
+python -m praisonai_tools.docs_generator
+
+# With options
+python -m praisonai_tools.docs_generator --layout granular
+```
+
+### Direct Script Execution
+
+```bash
+python generator.py --layout granular
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--layout` | Documentation layout: `compact` or `granular` | `granular` |
+| `--output` | Output directory path | Auto-detected |
+
+## Layouts
+
+### Compact Layout
+- Single page per module
+- Classes and functions inline
+
+### Granular Layout (Recommended)
+- Separate pages for each class and function
+- Module hub pages with links to components
+- Better navigation and searchability
+
+## Features
+
+- **Dynamic lazy-loading support**: Captures `_LAZY_IMPORTS`, `_LAZY_GROUPS`, `TOOL_MAPPINGS`
+- **Recursive scanning**: Scans all `__init__.py` files in package tree
+- **MDX output**: Mintlify-compatible MDX format
+- **Navigation generation**: Auto-updates `docs.json` navigation
+- **Icon support**: Maps modules to Font Awesome icons
+
+## Supported Packages
+
+- `praisonaiagents` (Python Core SDK)
+- `praisonai` (Python Wrapper)
+- TypeScript SDK (`praisonai-ts`)
+
+## Output Structure
+
+```
+docs/sdk/reference/
+├── praisonaiagents/
+│   ├── modules/      # Module hub pages
+│   ├── classes/      # Class pages
+│   └── functions/    # Function pages
+├── praisonai/
+│   └── ...
+└── typescript/
+    └── ...
+```

praisonai_tools/docs_generator/generator.py

@@ -341,23 +341,63 @@ def __init__(self, package_path: Path, package_name: str):
         self._load_lazy_imports()
 
     def _load_lazy_imports(self):
-        """Load _LAZY_IMPORTS from __init__.py if available."""
-        init_file = self.package_path / "__init__.py"
-        if not init_file.exists():
-            return
+        """Load _LAZY_IMPORTS and _LAZY_GROUPS from all __init__.py files.
         
-        try:
-            content = init_file.read_text()
-            match = re.search(r'_LAZY_IMPORTS\s*=\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}', content, re.DOTALL)
-            if not match:
-                return
-            
+        Recursively scans the package and all submodules for lazy import patterns.
+        Supports two patterns:
+        1. _LAZY_IMPORTS: flat dict of symbol -> (module, symbol)
+        2. _LAZY_GROUPS: nested dict of group -> {symbol: (module, symbol)}
+        """
+        # Scan all __init__.py files in the package
+        init_files = list(self.package_path.rglob("__init__.py"))
+        
+        for init_file in init_files:
+            try:
+                content = init_file.read_text()
+                self._parse_lazy_patterns(content)
+            except Exception:
+                pass
+    
+    def _parse_lazy_patterns(self, content: str):
+        """Parse various lazy loading patterns from file content.
+        
+        Supports patterns:
+        1. _LAZY_IMPORTS: flat dict of symbol -> (module, symbol)
+        2. _LAZY_GROUPS: nested dict of group -> {symbol: (module, symbol)}
+        3. TOOL_MAPPINGS: dict of symbol -> (module, class_or_none)
+        4. __all__: explicit export list (fallback for inline __getattr__)
+        """
+        # Pattern 1: _LAZY_IMPORTS (flat dict)
+        match = re.search(r'_LAZY_IMPORTS\s*=\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}', content, re.DOTALL)
+        if match:
             dict_content = match.group(1)
             pattern = r"'(\w+)':\s*\('([^']+)',\s*'([^']+)'\)"
             for m in re.finditer(pattern, dict_content):
                 self._lazy_imports[m.group(1)] = (m.group(2), m.group(3))
-        except Exception:
-            pass
+        
+        # Pattern 2: _LAZY_GROUPS (nested dict used by hooks, etc.)
+        match = re.search(r'_LAZY_GROUPS\s*=\s*\{(.+?)\n\}', content, re.DOTALL)
+        if match:
+            groups_content = match.group(1)
+            # Parse all symbol -> (module, symbol) pairs within groups
+            pattern = r"'(\w+)':\s*\('([^']+)',\s*'([^']+)'\)"
+            for m in re.finditer(pattern, groups_content):
+                symbol_name = m.group(1)
+                module_path = m.group(2)
+                self._lazy_imports[symbol_name] = (module_path, symbol_name)
+        
+        # Pattern 3: TOOL_MAPPINGS (used by tools/__init__.py)
+        match = re.search(r'TOOL_MAPPINGS\s*=\s*\{(.+?)\n\}', content, re.DOTALL)
+        if match:
+            mappings_content = match.group(1)
+            # Parse 'symbol': ('.module', None) or 'symbol': ('.module', 'ClassName')
+            pattern = r"'(\w+)':\s*\('([^']+)',\s*(?:None|'([^']*)')\)"
+            for m in re.finditer(pattern, mappings_content):
+                symbol_name = m.group(1)
+                self._lazy_imports[symbol_name] = (m.group(2), symbol_name)
+
+
+
 
     def get_modules(self) -> List[str]:
         """Get list of modules to document."""

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "praisonai-tools"
-version = "0.2.11"
+version = "0.2.12"
 description = "Extended tools for PraisonAI Agents"
 authors = [
     {name = "Mervin Praison"}