code2docs 0.1.2__tar.gz → 0.1.4__tar.gz

{code2docs-0.1.2 → code2docs-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2docs
-Version: 0.1.2
+Version: 0.1.4
 Summary: Auto-generate and sync project documentation from source code analysis
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -40,7 +40,7 @@ Dynamic: license-file
 
 # code2docs
 
-![version](https://img.shields.io/badge/version-0.1.2-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-0.1.4-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.
 

{code2docs-0.1.2 → code2docs-0.1.4}/README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-0.1.2-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-0.1.4-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.
 

{code2docs-0.1.2 → code2docs-0.1.4}/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__ = "0.1.2"
+__version__ = "0.1.4"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/analyzers/docstring_extractor.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
-from code2llm.core.models import AnalysisResult, FunctionInfo, ClassInfo
+from code2llm.api import AnalysisResult, FunctionInfo, ClassInfo
 
 
 @dataclass
@@ -38,44 +38,53 @@ class DocstringExtractor:
         return docs
 
     def parse(self, docstring: str) -> DocstringInfo:
-        """Parse a docstring into structured sections."""
+        """Parse a docstring into structured sections (orchestrator)."""
         if not docstring:
             return DocstringInfo(raw="")
 
         lines = docstring.strip().splitlines()
         info = DocstringInfo(raw=docstring)
+        info.summary = self._extract_summary(lines)
+        self._parse_sections(lines[1:], info)
+        return info
 
-        if lines:
-            info.summary = lines[0].strip()
-
-        # Simple parser for Google/Numpy/Sphinx styles
+    @staticmethod
+    def _extract_summary(lines: List[str]) -> str:
+        """Extract the first-line summary."""
+        return lines[0].strip() if lines else ""
+
+    @staticmethod
+    def _classify_section(line: str) -> Optional[str]:
+        """Classify a line as a section header, or return None."""
+        lower = line.strip().lower()
+        if lower.startswith(("args:", "parameters:", "params:")):
+            return "params"
+        if lower.startswith(("returns:", "return:")):
+            return "returns"
+        if lower.startswith(("raises:", "raise:")):
+            return "raises"
+        if lower.startswith(("example:", "examples:", ">>>")):
+            return "examples"
+        return None
+
+    def _parse_sections(self, lines: List[str], info: DocstringInfo) -> None:
+        """Walk remaining lines, dispatching content to the right section."""
         current_section = "description"
         desc_lines: List[str] = []
-        param_lines: List[Tuple[str, str]] = []
 
-        for line in lines[1:]:
+        for line in lines:
             stripped = line.strip()
-            lower = stripped.lower()
 
-            if lower.startswith(("args:", "parameters:", "params:")):
-                current_section = "params"
-                continue
-            elif lower.startswith(("returns:", "return:")):
-                current_section = "returns"
-                continue
-            elif lower.startswith(("raises:", "raise:")):
-                current_section = "raises"
-                continue
-            elif lower.startswith(("example:", "examples:", ">>>")):
-                current_section = "examples"
-                if stripped.startswith(">>>"):
+            new_section = self._classify_section(stripped)
+            if new_section is not None:
+                current_section = new_section
+                if current_section == "examples" and stripped.startswith(">>>"):
                     info.examples.append(stripped)
                 continue
 
             if current_section == "description":
                 desc_lines.append(stripped)
             elif current_section == "params" and stripped:
-                # Parse "name: description" or "name (type): description"
                 if ":" in stripped:
                     pname, pdesc = stripped.split(":", 1)
                     info.params[pname.strip()] = pdesc.strip()
@@ -87,7 +96,6 @@ class DocstringExtractor:
                 info.examples.append(stripped)
 
         info.description = "\n".join(desc_lines).strip()
-        return info
 
     def coverage_report(self, result: AnalysisResult) -> Dict[str, float]:
         """Calculate docstring coverage statistics."""

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/analyzers/endpoint_detector.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from code2llm.core.models import AnalysisResult, FunctionInfo
+from code2llm.api import AnalysisResult, FunctionInfo
 
 
 @dataclass

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/analyzers/project_scanner.py

@@ -3,9 +3,7 @@
 from pathlib import Path
 from typing import Optional
 
-from code2llm import Config, FAST_CONFIG
-from code2llm.core.analyzer import ProjectAnalyzer
-from code2llm.core.models import AnalysisResult
+from code2llm.api import Config, FAST_CONFIG, AnalysisResult, analyze
 
 from ..config import Code2DocsConfig
 
@@ -35,8 +33,7 @@ class ProjectScanner:
 
     def analyze(self, project_path: str) -> AnalysisResult:
         """Analyze a project and return AnalysisResult for doc generation."""
-        analyzer = ProjectAnalyzer(self._llm_config)
-        return analyzer.analyze_project(project_path)
+        return analyze(project_path, self._llm_config)
 
 
 def analyze_and_document(project_path: str, config: Optional[Code2DocsConfig] = None) -> AnalysisResult:

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/cli.py

@@ -9,7 +9,23 @@ import click
 from .config import Code2DocsConfig
 
 
-@click.group(invoke_without_command=True)
+class DefaultGroup(click.Group):
+    """Click Group that routes unknown subcommands to 'generate'."""
+
+    def parse_args(self, ctx, args):
+        if not args:
+            args = ["generate"]
+        elif args[0] not in self.commands and args[0] not in ("--help", "-h"):
+            args = ["generate"] + args
+        return super().parse_args(ctx, args)
+
+
+@click.group(cls=DefaultGroup)
+def main():
+    """code2docs — Auto-generate project documentation from source code."""
+
+
+@main.command()
 @click.argument("project_path", default=".", type=click.Path(exists=True))
 @click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
 @click.option("--readme-only", is_flag=True, help="Generate only README.md")
@@ -17,21 +33,8 @@ from .config import Code2DocsConfig
 @click.option("--output", "-o", default=None, help="Output directory for docs")
 @click.option("--verbose", "-v", is_flag=True, help="Verbose output")
 @click.option("--dry-run", is_flag=True, help="Show what would be generated without writing")
-@click.pass_context
-def main(ctx, project_path, config_path, readme_only, sections, output, verbose, dry_run):
-    """code2docs — Auto-generate project documentation from source code.
-
-    Analyzes PROJECT_PATH using code2llm and generates human-readable documentation.
-    """
-    if ctx.invoked_subcommand is not None:
-        ctx.ensure_object(dict)
-        ctx.obj["project_path"] = project_path
-        ctx.obj["config_path"] = config_path
-        ctx.obj["verbose"] = verbose
-        ctx.obj["dry_run"] = dry_run
-        return
-
-    # Default action: full generation
+def generate(project_path, config_path, readme_only, sections, output, verbose, dry_run):
+    """Generate documentation (default command)."""
     config = _load_config(project_path, config_path)
     if verbose:
         config.verbose = True

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/generators/api_reference_gen.py

@@ -5,7 +5,7 @@ from typing import Dict, List, Optional
 
 from jinja2 import Environment, PackageLoader, select_autoescape
 
-from code2llm.core.models import AnalysisResult, FunctionInfo, ClassInfo, ModuleInfo
+from code2llm.api import AnalysisResult, FunctionInfo, ClassInfo, ModuleInfo
 
 from ..config import Code2DocsConfig
 
@@ -61,67 +61,79 @@ class ApiReferenceGenerator:
         return "\n".join(lines) + "\n"
 
     def _generate_module_api(self, mod_name: str, mod_info: ModuleInfo) -> str:
-        """Generate API reference for a single module."""
-        lines = [f"# `{mod_name}`\n"]
+        """Generate API reference for a single module (orchestrator)."""
+        parts: List[str] = [
+            self._render_api_header(mod_name, mod_info),
+            self._render_api_classes(mod_name),
+            self._render_api_functions(mod_name),
+            self._render_api_imports(mod_info),
+        ]
+        return "\n".join(p for p in parts if p)
 
-        # Source info
-        lines.append(f"> Source: `{mod_info.file}`\n")
+    def _render_api_header(self, mod_name: str, mod_info: ModuleInfo) -> str:
+        """Render module header with source info."""
+        return f"# `{mod_name}`\n\n> Source: `{mod_info.file}`\n"
 
-        # Classes in this module
+    def _render_api_classes(self, mod_name: str) -> str:
+        """Render classes with their method signatures."""
         module_classes = {
             k: v for k, v in self.result.classes.items()
             if v.module == mod_name or k.startswith(mod_name + ".")
         }
-        if module_classes:
-            lines.append("## Classes\n")
-            for cls_name, cls_info in sorted(module_classes.items()):
-                lines.append(f"### `{cls_info.name}`\n")
-                if cls_info.bases:
-                    lines.append(f"Inherits from: {', '.join(f'`{b}`' for b in cls_info.bases)}\n")
-                if cls_info.docstring:
-                    lines.append(f"{cls_info.docstring.strip()}\n")
-
-                # Methods of this class
-                methods = self._get_class_methods(cls_info)
-                if methods:
-                    lines.append("#### Methods\n")
-                    for method in methods:
-                        sig = self._format_signature(method)
-                        doc_line = ""
-                        if method.docstring:
-                            doc_line = f" — {method.docstring.splitlines()[0]}"
-                        cc = method.complexity.get("cyclomatic", 0)
-                        cc_badge = f" ⚠️ CC={cc}" if cc > 10 else ""
-                        lines.append(f"- `{sig}`{doc_line}{cc_badge}")
-                    lines.append("")
-
-        # Standalone functions in this module
+        if not module_classes:
+            return ""
+        lines = ["## Classes\n"]
+        for cls_name, cls_info in sorted(module_classes.items()):
+            lines.append(f"### `{cls_info.name}`\n")
+            if cls_info.bases:
+                lines.append(f"Inherits from: {', '.join(f'`{b}`' for b in cls_info.bases)}\n")
+            if cls_info.docstring:
+                lines.append(f"{cls_info.docstring.strip()}\n")
+            methods = self._get_class_methods(cls_info)
+            if methods:
+                lines.append("#### Methods\n")
+                for method in methods:
+                    sig = self._format_signature(method)
+                    doc_line = ""
+                    if method.docstring:
+                        doc_line = f" — {method.docstring.splitlines()[0]}"
+                    cc = method.complexity.get("cyclomatic", 0)
+                    cc_badge = f" ⚠️ CC={cc}" if cc > 10 else ""
+                    lines.append(f"- `{sig}`{doc_line}{cc_badge}")
+                lines.append("")
+        return "\n".join(lines)
+
+    def _render_api_functions(self, mod_name: str) -> str:
+        """Render standalone functions with signatures and complexity."""
         module_functions = {
             k: v for k, v in self.result.functions.items()
             if (v.module == mod_name or k.startswith(mod_name + "."))
             and not v.is_method
         }
-        if module_functions:
-            lines.append("## Functions\n")
-            for func_name, func_info in sorted(module_functions.items()):
-                sig = self._format_signature(func_info)
-                lines.append(f"### `{sig}`\n")
-                if func_info.docstring:
-                    lines.append(f"{func_info.docstring.strip()}\n")
-                cc = func_info.complexity.get("cyclomatic", 0)
-                if cc:
-                    lines.append(f"- Complexity: {cc}")
-                if func_info.calls:
-                    lines.append(f"- Calls: {', '.join(f'`{c}`' for c in func_info.calls[:10])}")
-                lines.append("")
-
-        # Imports
-        if mod_info.imports:
-            lines.append("## Imports\n")
-            for imp in sorted(mod_info.imports):
-                lines.append(f"- `{imp}`")
+        if not module_functions:
+            return ""
+        lines = ["## Functions\n"]
+        for func_name, func_info in sorted(module_functions.items()):
+            sig = self._format_signature(func_info)
+            lines.append(f"### `{sig}`\n")
+            if func_info.docstring:
+                lines.append(f"{func_info.docstring.strip()}\n")
+            cc = func_info.complexity.get("cyclomatic", 0)
+            if cc:
+                lines.append(f"- Complexity: {cc}")
+            if func_info.calls:
+                lines.append(f"- Calls: {', '.join(f'`{c}`' for c in func_info.calls[:10])}")
             lines.append("")
+        return "\n".join(lines)
 
+    def _render_api_imports(self, mod_info: ModuleInfo) -> str:
+        """Render module imports list."""
+        if not mod_info.imports:
+            return ""
+        lines = ["## Imports\n"]
+        for imp in sorted(mod_info.imports):
+            lines.append(f"- `{imp}`")
+        lines.append("")
         return "\n".join(lines)
 
     def _get_class_methods(self, cls_info: ClassInfo) -> List[FunctionInfo]:

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/generators/architecture_gen.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from typing import Dict, List, Set
 
-from code2llm.core.models import AnalysisResult, ModuleInfo
+from code2llm.api import AnalysisResult, ModuleInfo
 
 from ..config import Code2DocsConfig
 

{code2docs-0.1.2 → code2docs-0.1.4}/code2docs/generators/changelog_gen.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from code2llm.core.models import AnalysisResult
+from code2llm.api import AnalysisResult
 
 from ..config import Code2DocsConfig
 

code2docs-0.1.4/code2docs/generators/coverage_gen.py

@@ -0,0 +1,85 @@
+"""Docstring coverage report generator."""
+
+from typing import Dict, List
+
+from code2llm.api import AnalysisResult
+
+from ..config import Code2DocsConfig
+from ..analyzers.docstring_extractor import DocstringExtractor
+
+
+class CoverageGenerator:
+    """Generate docs/coverage.md — docstring coverage report."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+        self._extractor = DocstringExtractor()
+
+    def generate(self) -> str:
+        """Generate coverage.md content."""
+        project_name = self.config.project_name or "Project"
+        report = self._extractor.coverage_report(self.result)
+
+        lines = [
+            f"# {project_name} — Docstring Coverage\n",
+            self._render_summary(report),
+            "",
+            "## Per-Module Breakdown\n",
+            self._render_per_module(),
+            "",
+            "## Undocumented Items\n",
+            self._render_undocumented(),
+            "",
+        ]
+        return "\n".join(lines)
+
+    @staticmethod
+    def _render_summary(report: Dict[str, float]) -> str:
+        """Render overall coverage summary."""
+        overall = report.get("overall_coverage", 0)
+        badge = "🟢" if overall >= 80 else "🟡" if overall >= 50 else "🔴"
+        lines = [
+            f"{badge} **Overall coverage: {overall:.1f}%**\n",
+            "| Category | Documented | Total | Coverage |",
+            "|----------|-----------|-------|----------|",
+            f"| Functions | {report['functions_documented']} | {report['functions_total']} | {report['functions_coverage']:.1f}% |",
+            f"| Classes | {report['classes_documented']} | {report['classes_total']} | {report['classes_coverage']:.1f}% |",
+        ]
+        return "\n".join(lines)
+
+    def _render_per_module(self) -> str:
+        """Render per-module coverage table."""
+        rows: List[str] = [
+            "| Module | Functions | Classes | Coverage |",
+            "|--------|-----------|---------|----------|",
+        ]
+        for mod_name in sorted(self.result.modules.keys()):
+            funcs = [f for f in self.result.functions.values()
+                     if f.module == mod_name and not f.is_method]
+            classes = [c for c in self.result.classes.values()
+                       if c.module == mod_name]
+            total = len(funcs) + len(classes)
+            documented = (sum(1 for f in funcs if f.docstring) +
+                          sum(1 for c in classes if c.docstring))
+            pct = (documented / total * 100) if total else 100.0
+            badge = "🟢" if pct >= 80 else "🟡" if pct >= 50 else "🔴"
+            rows.append(
+                f"| `{mod_name}` | {sum(1 for f in funcs if f.docstring)}/{len(funcs)} "
+                f"| {sum(1 for c in classes if c.docstring)}/{len(classes)} "
+                f"| {badge} {pct:.0f}% |"
+            )
+        return "\n".join(rows)
+
+    def _render_undocumented(self) -> str:
+        """List all undocumented public functions and classes."""
+        items: List[str] = []
+        for name, func in sorted(self.result.functions.items()):
+            if not func.docstring and not func.is_private and not func.is_method:
+                items.append(f"- `{name}` ({func.file}:{func.line})")
+        for name, cls in sorted(self.result.classes.items()):
+            if not cls.docstring:
+                items.append(f"- `{name}` ({cls.file}:{cls.line})")
+        if not items:
+            return "_All public items are documented._ ✅"
+        return "\n".join(items)

code2docs-0.1.4/code2docs/generators/depgraph_gen.py

@@ -0,0 +1,112 @@
+"""Dependency graph generator — Mermaid diagram from coupling matrix."""
+
+from typing import Dict, List, Set, Tuple
+
+from code2llm.api import AnalysisResult, ModuleInfo
+
+from ..config import Code2DocsConfig
+
+
+class DepGraphGenerator:
+    """Generate docs/dependency-graph.md with Mermaid diagrams."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+
+    def generate(self) -> str:
+        """Generate dependency-graph.md content."""
+        project_name = self.config.project_name or "Project"
+        edges = self._collect_edges()
+        in_degree, out_degree = self._calc_degrees(edges)
+
+        lines = [
+            f"# {project_name} — Dependency Graph\n",
+            f"> {len(self.result.modules)} modules, "
+            f"{len(edges)} dependency edges\n",
+            "## Module Dependencies\n",
+            self._render_mermaid(edges),
+            "",
+            "## Coupling Matrix\n",
+            self._render_matrix(edges),
+            "",
+            "## Fan-in / Fan-out\n",
+            self._render_degree_table(in_degree, out_degree),
+            "",
+        ]
+        return "\n".join(lines)
+
+    def _collect_edges(self) -> List[Tuple[str, str]]:
+        """Build directed edges from module imports."""
+        edges: List[Tuple[str, str]] = []
+        module_names = set(self.result.modules.keys())
+
+        for mod_name, mod_info in self.result.modules.items():
+            for imp in mod_info.imports:
+                for other in module_names:
+                    if mod_name != other and self._import_matches(imp, other):
+                        edges.append((mod_name, other))
+        return sorted(set(edges))
+
+    @staticmethod
+    def _import_matches(imp: str, module: str) -> bool:
+        """Check if an import string refers to a known module."""
+        return imp == module or imp.startswith(module + ".")
+
+    def _render_mermaid(self, edges: List[Tuple[str, str]]) -> str:
+        """Render Mermaid graph from edges."""
+        lines = ["```mermaid", "graph LR"]
+        for src, tgt in edges:
+            s = src.split(".")[-1]
+            t = tgt.split(".")[-1]
+            lines.append(f"    {s} --> {t}")
+        if not edges:
+            lines.append("    note[No internal dependencies]")
+        lines.append("```")
+        return "\n".join(lines)
+
+    def _render_matrix(self, edges: List[Tuple[str, str]]) -> str:
+        """Render a coupling matrix as a Markdown table."""
+        mods = sorted(self.result.modules.keys())
+        if not mods:
+            return "_No modules._"
+        short = {m: m.split(".")[-1] for m in mods}
+        edge_set = set(edges)
+
+        header = "| | " + " | ".join(short[m] for m in mods) + " |"
+        sep = "| --- | " + " | ".join("---" for _ in mods) + " |"
+        rows = [header, sep]
+        for src in mods:
+            cells = []
+            for tgt in mods:
+                if src == tgt:
+                    cells.append("·")
+                elif (src, tgt) in edge_set:
+                    cells.append("→")
+                else:
+                    cells.append("")
+            rows.append(f"| **{short[src]}** | " + " | ".join(cells) + " |")
+        return "\n".join(rows)
+
+    @staticmethod
+    def _calc_degrees(edges: List[Tuple[str, str]]) -> Tuple[Dict[str, int], Dict[str, int]]:
+        """Calculate in-degree and out-degree per module."""
+        in_deg: Dict[str, int] = {}
+        out_deg: Dict[str, int] = {}
+        for src, tgt in edges:
+            out_deg[src] = out_deg.get(src, 0) + 1
+            in_deg[tgt] = in_deg.get(tgt, 0) + 1
+        return in_deg, out_deg
+
+    def _render_degree_table(self, in_deg: Dict[str, int], out_deg: Dict[str, int]) -> str:
+        """Render fan-in/fan-out table."""
+        mods = sorted(self.result.modules.keys())
+        lines = [
+            "| Module | Fan-in | Fan-out |",
+            "|--------|--------|---------|",
+        ]
+        for m in mods:
+            fi = in_deg.get(m, 0)
+            fo = out_deg.get(m, 0)
+            lines.append(f"| `{m}` | {fi} | {fo} |")
+        return "\n".join(lines)