code2docs 3.0.3__tar.gz → 3.0.5__tar.gz

{code2docs-3.0.3 → code2docs-3.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2docs
-Version: 3.0.3
+Version: 3.0.5
 Summary: Auto-generate and sync project documentation from source code analysis
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -50,7 +50,7 @@ Dynamic: license-file
 
 # code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -190,7 +190,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.3 → code2docs-3.0.5}/README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -140,7 +140,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs/__init__.py

@@ -5,7 +5,7 @@ Uses code2llm's AnalysisResult to produce human-readable documentation:
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = "3.0.3"
+__version__ = "3.0.5"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs/cli.py

@@ -40,8 +40,9 @@ def main():
 @click.option("--dry-run", is_flag=True, help="Show what would be generated without writing")
 @click.option("--llm", "llm_model", default=None,
               help="Enable LLM-assisted generation (e.g. openai/gpt-4o-mini, ollama/llama3)")
+@click.option("--org-name", default=None, help="Organization name for org-mode README generation")
 def generate(project_path, config_path, readme_only, sections, output, verbose, dry_run,
-             llm_model):
+             llm_model, org_name):
     """Generate documentation (default command)."""
     config = _load_config(project_path, config_path)
     if verbose:
@@ -53,6 +54,8 @@ def generate(project_path, config_path, readme_only, sections, output, verbose,
     if llm_model:
         config.llm.enabled = True
         config.llm.model = llm_model
+    if org_name:
+        config.org_name = org_name
 
     _run_generate(project_path, config, readme_only=readme_only, dry_run=dry_run)
 

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs/config.py

@@ -108,6 +108,7 @@ class Code2DocsConfig:
     output: str = "./docs/"
     readme_output: str = "./README.md"
     repo_url: str = ""  # GitHub/GitLab URL for source links (auto-detected from git)
+    org_name: str = ""  # Organization name for org-mode README generation
 
     readme: ReadmeConfig = field(default_factory=ReadmeConfig)
     docs: DocsConfig = field(default_factory=DocsConfig)

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs/generators/_registry_adapters.py

@@ -240,6 +240,35 @@ class Code2LlmAdapter(BaseGenerator):
         return "⚠️ project/ (no files generated)"
 
 
+class OrgReadmeAdapter(BaseGenerator):
+    """Adapter for organization README generation."""
+    name = "org_readme"
+
+    def should_run(self, *, readme_only: bool = False) -> bool:
+        # Only run if org_name is set in config
+        return hasattr(self.config, 'org_name') and bool(self.config.org_name)
+
+    def run(self, ctx: GenerateContext) -> Optional[str]:
+        from .org_readme_gen import OrgReadmeGenerator
+        
+        org_name = getattr(self.config, 'org_name', '')
+        if not org_name:
+            return None
+            
+        gen = OrgReadmeGenerator(self.config, str(ctx.project), org_name)
+        content = gen.generate()
+        
+        if ctx.dry_run:
+            click.echo(f"\n--- {org_name} README ({len(content)} chars) ---")
+            preview = content[:500] + "..." if len(content) > 500 else content
+            click.echo(preview)
+            return None
+        
+        readme_path = ctx.docs_dir / "README.md"
+        gen.write(str(readme_path), content)
+        return f"✅ {readme_path.relative_to(ctx.project)}"
+
+
 ALL_ADAPTERS = [
     ReadmeGeneratorAdapter,
     ApiReferenceAdapter,
@@ -254,4 +283,5 @@ ALL_ADAPTERS = [
     ContributingAdapter,
     MkDocsAdapter,
     Code2LlmAdapter,
+    OrgReadmeAdapter,
 ]

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs/generators/examples_gen.py

@@ -138,15 +138,18 @@ class ExamplesGenerator:
 
         # --- Example 1: Config (define first so later examples can use it) ---
         config_cls = self._find_class_by_name("Code2DocsConfig")
+        project_name = self.config.project_name or Path(self.result.project_path).name
+        source = self.config.source or "./"
+        output = self.config.output or "./docs"
         if config_cls:
             lines.append('# ' + '=' * 50)
             lines.append("# Example 1: Configuration")
             lines.append('# ' + '=' * 50)
             lines.append("")
             lines.append(f"config = {config_cls.name}(")
-            lines.append('    project_name="my-project",')
-            lines.append('    source="./src",')
-            lines.append('    output="./docs",')
+            lines.append(f'    project_name="{project_name}",')
+            lines.append(f'    source="{source}",')
+            lines.append(f'    output="{output}",')
             lines.append("    verbose=True,")
             lines.append(")")
             lines.append("")
@@ -157,20 +160,22 @@ class ExamplesGenerator:
         lines.append("# Example 2: Generate documentation")
         lines.append('# ' + '=' * 50)
         lines.append("")
+        
+        project_path = f'"./{project_name}"' if project_name != "." else '"./"'
 
         gen_func = self._find_function_by_name("generate_readme")
         if gen_func:
             lines.append("# Generate a README for your project")
-            lines.append('generate_readme("./my-project", output="README.md")')
+            lines.append(f'generate_readme({project_path}, output="README.md")')
             lines.append("")
 
         docs_func = self._find_function_by_name("generate_docs")
         if docs_func:
             lines.append("# Generate all documentation")
             if config_cls:
-                lines.append('docs = generate_docs("./my-project", config=config)')
+                lines.append(f'docs = generate_docs({project_path}, config=config)')
             else:
-                lines.append('docs = generate_docs("./my-project")')
+                lines.append(f'docs = generate_docs({project_path})')
             lines.append('print(f"Generated {len(docs)} documentation sections")')
             lines.append("")
 
@@ -185,7 +190,7 @@ class ExamplesGenerator:
             lines.append(f"from {pkg}.analyzers.project_scanner import ProjectScanner")
             lines.append("")
             lines.append("scanner = ProjectScanner(config)")
-            lines.append('result = scanner.analyze("./my-project")')
+            lines.append(f'result = scanner.analyze({project_path})')
             lines.append("")
             lines.append('print(f"Found {len(result.functions)} functions")')
             lines.append('print(f"Found {len(result.classes)} classes")')
@@ -229,7 +234,7 @@ class ExamplesGenerator:
             lines.append("# Step 1: Analyze the project")
             lines.append("config = Code2DocsConfig(project_name=\"my-project\")")
             lines.append("scanner = ProjectScanner(config)")
-            lines.append('result = scanner.analyze("./my-project")')
+            lines.append('result = scanner.analyze(f"./${project_name_adv}") if project_name_adv != "." else result = scanner.analyze("./")')
             lines.append("")
 
             for i, cls in enumerate(gen_classes[:4], start=2):
@@ -389,8 +394,8 @@ class ExamplesGenerator:
         args = [a for a in func.args if a not in ("self", "cls")]
         parts = []
         for arg in args[:5]:
-            val = _ARG_EXAMPLES.get(arg)
-            if not val:
+            val = self._get_example_value(arg)
+            if not val or val == '"..."':
                 # Try type hint
                 val = self._example_from_type(func, arg)
             if not val:
@@ -398,17 +403,18 @@ class ExamplesGenerator:
             parts.append(f"{arg}={val}" if len(args) > 1 else val)
         return ", ".join(parts)
 
-    @staticmethod
-    def _example_from_type(func: FunctionInfo, arg: str) -> Optional[str]:
+    def _example_from_type(self, func: FunctionInfo, arg: str) -> Optional[str]:
         """Try to infer example value from type annotation."""
+        project_name = self.config.project_name or Path(self.result.project_path).name
+        
         # FunctionInfo.returns gives return type, but arg types
         # are not always available; use naming heuristics
         if "path" in arg.lower():
-            return '"./my-project"'
+            return f'"./{project_name}"'
         if "name" in arg.lower():
-            return '"my-project"'
+            return f'"{project_name}"'
         if "dir" in arg.lower():
-            return '"./docs"'
+            return f'"{self.config.output}"' if self.config.output else '"./docs"'
         if arg.startswith("is_") or arg.startswith("enable"):
             return "True"
         if "count" in arg.lower() or "max" in arg.lower() or "min" in arg.lower():

code2docs-3.0.5/code2docs/generators/org_readme_gen.py

@@ -0,0 +1,227 @@
+"""Organization README generator - generates overview of multiple projects."""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from code2llm.api import AnalysisResult
+
+from ..config import Code2DocsConfig
+from ..analyzers.project_scanner import ProjectScanner
+
+
+class OrgReadmeGenerator:
+    """Generate organization README with list of projects and brief descriptions."""
+
+    def __init__(self, config: Code2DocsConfig, org_path: str, org_name: str = ""):
+        self.config = config
+        self.org_path = Path(org_path).resolve()
+        self.org_name = org_name or self.org_path.name
+        self.scanner = ProjectScanner(config)
+
+    def generate(self) -> str:
+        """Generate organization README content."""
+        projects = self._discover_projects()
+        
+        lines = [
+            f"# {self.org_name}\n",
+            f"Projects in the {self.org_name} organization.\n",
+            f"**{len(projects)}** projects discovered.\n",
+            "## Projects\n",
+        ]
+        
+        for project_name, project_info in sorted(projects.items()):
+            lines.append(self._render_project_section(project_name, project_info))
+            lines.append("")
+        
+        return "\n".join(lines)
+
+    def _discover_projects(self) -> Dict[str, Dict]:
+        """Discover all projects in organization directory."""
+        projects = {}
+        
+        for item in self.org_path.iterdir():
+            if not item.is_dir():
+                continue
+            if item.name.startswith(".") or item.name.startswith("__"):
+                continue
+            
+            project_info = self._analyze_project(item)
+            if project_info:
+                projects[item.name] = project_info
+        
+        return projects
+
+    def _analyze_project(self, project_path: Path) -> Optional[Dict]:
+        """Analyze a single project and return summary info."""
+        try:
+            result = self.scanner.analyze(str(project_path))
+            
+            # Extract description from first module docstring or pyproject.toml
+            description = self._extract_description(project_path, result)
+            
+            # Count functions, classes, modules
+            func_count = len(result.functions)
+            class_count = len(result.classes)
+            module_count = len(result.modules)
+            
+            # Get version from pyproject.toml if available
+            version = self._get_version(project_path)
+            
+            # Get repo URL from git or config
+            repo_url = self._get_repo_url(project_path)
+            
+            return {
+                "name": project_path.name,
+                "description": description,
+                "version": version,
+                "stats": {
+                    "functions": func_count,
+                    "classes": class_count,
+                    "modules": module_count,
+                },
+                "repo_url": repo_url,
+                "path": str(project_path),
+            }
+        except Exception:
+            return None
+
+    def _extract_description(self, project_path: Path, result: AnalysisResult) -> str:
+        """Extract short description from project (max 5 lines)."""
+        # Try pyproject.toml first
+        try:
+            import tomllib
+            pyproject = project_path / "pyproject.toml"
+            if pyproject.exists():
+                with open(pyproject, "rb") as f:
+                    data = tomllib.load(f)
+                    desc = data.get("project", {}).get("description", "")
+                    if desc:
+                        # Limit to ~5 lines worth of content
+                        return self._truncate_description(desc)
+        except Exception:
+            pass
+        
+        # Try first package docstring
+        for mod in result.modules.values():
+            if mod.is_package and hasattr(mod, "docstring") and mod.docstring:
+                return self._truncate_description(mod.docstring)
+        
+        # Try README.md first paragraph
+        readme = project_path / "README.md"
+        if readme.exists():
+            try:
+                content = readme.read_text(encoding="utf-8")
+                # Find first paragraph after title
+                lines = content.split("\n")
+                for i, line in enumerate(lines):
+                    if line.startswith("# "):
+                        # Get next non-empty lines
+                        desc_lines = []
+                        for j in range(i + 1, min(i + 10, len(lines))):
+                            if lines[j].strip() and not lines[j].startswith("#"):
+                                desc_lines.append(lines[j].strip())
+                            if len(desc_lines) >= 5:
+                                break
+                        if desc_lines:
+                            return " ".join(desc_lines)
+            except Exception:
+                pass
+        
+        return "No description available."
+
+    def _truncate_description(self, desc: str, max_chars: int = 300) -> str:
+        """Truncate description to ~5 lines of content."""
+        lines = desc.strip().split("\n")
+        # Filter out empty lines and headers
+        content_lines = [l.strip() for l in lines if l.strip() and not l.startswith("#")]
+        
+        result = []
+        char_count = 0
+        for line in content_lines[:5]:
+            if char_count + len(line) > max_chars:
+                remaining = max_chars - char_count
+                if remaining > 20:
+                    result.append(line[:remaining] + "...")
+                break
+            result.append(line)
+            char_count += len(line)
+        
+        return " ".join(result) if result else "No description available."
+
+    def _get_version(self, project_path: Path) -> str:
+        """Get version from pyproject.toml or VERSION file."""
+        try:
+            import tomllib
+            pyproject = project_path / "pyproject.toml"
+            if pyproject.exists():
+                with open(pyproject, "rb") as f:
+                    data = tomllib.load(f)
+                    return data.get("project", {}).get("version", "")
+        except Exception:
+            pass
+        
+        version_file = project_path / "VERSION"
+        if version_file.exists():
+            return version_file.read_text(encoding="utf-8").strip()
+        
+        return ""
+
+    def _get_repo_url(self, project_path: Path) -> str:
+        """Get repository URL from git or pyproject.toml."""
+        # Try pyproject.toml
+        try:
+            import tomllib
+            pyproject = project_path / "pyproject.toml"
+            if pyproject.exists():
+                with open(pyproject, "rb") as f:
+                    data = tomllib.load(f)
+                    urls = data.get("project", {}).get("urls", {})
+                    if urls:
+                        return urls.get("Repository", urls.get("Homepage", ""))
+        except Exception:
+            pass
+        
+        # Try git remote
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["git", "remote", "get-url", "origin"],
+                cwd=str(project_path),
+                capture_output=True, text=True, timeout=5,
+            )
+            if result.returncode == 0:
+                url = result.stdout.strip()
+                # Convert SSH to HTTPS
+                if url.startswith("git@"):
+                    url = url.replace(":", "/", 1).replace("git@", "https://", 1)
+                return url.removesuffix(".git")
+        except Exception:
+            pass
+        
+        return ""
+
+    def _render_project_section(self, name: str, info: Dict) -> str:
+        """Render a single project section (5 lines max)."""
+        lines = [f"### {name}"]
+        
+        # Line 1: Description
+        lines.append(info["description"])
+        
+        # Line 2: Stats
+        stats = info["stats"]
+        stats_line = f"📊 {stats['functions']} functions | {stats['classes']} classes | {stats['modules']} modules"
+        if info["version"]:
+            stats_line += f" | v{info['version']}"
+        lines.append(stats_line)
+        
+        # Line 3: Repo link if available
+        if info["repo_url"]:
+            lines.append(f"🔗 [{info['repo_url']}]({info['repo_url']})")
+        
+        return "\n".join(lines)
+
+    def write(self, output_path: str, content: str) -> None:
+        """Write README to output path."""
+        out_path = Path(output_path)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(content, encoding="utf-8")

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2docs
-Version: 3.0.3
+Version: 3.0.5
 Summary: Auto-generate and sync project documentation from source code analysis
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -50,7 +50,7 @@ Dynamic: license-file
 
 # code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -190,7 +190,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.5-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.3 → code2docs-3.0.5}/code2docs.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ code2docs/generators/examples_gen.py
 code2docs/generators/getting_started_gen.py
 code2docs/generators/mkdocs_gen.py
 code2docs/generators/module_docs_gen.py
+code2docs/generators/org_readme_gen.py
 code2docs/generators/readme_gen.py
 code2docs/sync/__init__.py
 code2docs/sync/differ.py

{code2docs-3.0.3 → code2docs-3.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code2docs"
-version = "3.0.3"
+version = "3.0.5"
 description = "Auto-generate and sync project documentation from source code analysis"
 readme = "README.md"
 requires-python = ">=3.9"