code2docs 0.1.1__py3-none-any.whl

code2docs/generators/api_reference_gen.py

@@ -0,0 +1,150 @@
+"""API reference documentation generator — per-module API docs."""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from code2llm.core.models import AnalysisResult, FunctionInfo, ClassInfo, ModuleInfo
+
+from ..config import Code2DocsConfig
+
+
+class ApiReferenceGenerator:
+    """Generate docs/api/ — per-module API reference from signatures."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+        self.env = Environment(
+            loader=PackageLoader("code2docs", "templates"),
+            autoescape=select_autoescape([]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def generate_all(self) -> Dict[str, str]:
+        """Generate API reference for all modules. Returns {filename: content}."""
+        files: Dict[str, str] = {}
+
+        # Index page
+        files["index.md"] = self._generate_index()
+
+        # Per-module pages
+        for mod_name, mod_info in sorted(self.result.modules.items()):
+            safe_name = mod_name.replace(".", "_").replace("/", "_")
+            filename = f"module_{safe_name}.md"
+            files[filename] = self._generate_module_api(mod_name, mod_info)
+
+        return files
+
+    def _generate_index(self) -> str:
+        """Generate API index page."""
+        lines = [
+            "# API Reference\n",
+            f"> Auto-generated from {len(self.result.modules)} modules | "
+            f"{len(self.result.functions)} functions | "
+            f"{len(self.result.classes)} classes\n",
+            "## Modules\n",
+        ]
+
+        for mod_name in sorted(self.result.modules.keys()):
+            mod = self.result.modules[mod_name]
+            safe_name = mod_name.replace(".", "_").replace("/", "_")
+            func_count = len(mod.functions)
+            class_count = len(mod.classes)
+            lines.append(
+                f"- [`{mod_name}`](module_{safe_name}.md) — "
+                f"{func_count} functions, {class_count} classes"
+            )
+
+        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"]
+
+        # Source info
+        lines.append(f"> Source: `{mod_info.file}`\n")
+
+        # Classes in this module
+        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
+        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}`")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _get_class_methods(self, cls_info: ClassInfo) -> List[FunctionInfo]:
+        """Get FunctionInfo objects for class methods."""
+        methods = []
+        for method_name in cls_info.methods:
+            # Try various qualified name patterns
+            for key in [method_name, f"{cls_info.qualified_name}.{method_name}"]:
+                if key in self.result.functions:
+                    methods.append(self.result.functions[key])
+                    break
+        return methods
+
+    @staticmethod
+    def _format_signature(func: FunctionInfo) -> str:
+        """Format a function signature string."""
+        args_str = ", ".join(func.args)
+        ret = f" → {func.returns}" if func.returns else ""
+        return f"{func.name}({args_str}){ret}"
+
+    def write_all(self, output_dir: str, files: Dict[str, str]) -> None:
+        """Write all generated API reference files."""
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        for filename, content in files.items():
+            (out / filename).write_text(content, encoding="utf-8")

code2docs/generators/architecture_gen.py

@@ -0,0 +1,192 @@
+"""Architecture documentation generator with Mermaid diagrams."""
+
+from pathlib import Path
+from typing import Dict, List, Set
+
+from code2llm.core.models import AnalysisResult, ModuleInfo
+
+from ..config import Code2DocsConfig
+
+
+class ArchitectureGenerator:
+    """Generate docs/architecture.md — architecture overview with diagrams."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+
+    def generate(self) -> str:
+        """Generate architecture documentation."""
+        project_name = self.config.project_name or Path(self.result.project_path).name
+
+        lines = [
+            f"# {project_name} — Architecture\n",
+            f"> Auto-generated from {len(self.result.modules)} modules, "
+            f"{len(self.result.functions)} functions, "
+            f"{len(self.result.classes)} classes\n",
+        ]
+
+        # Module dependency graph
+        lines.append("## Module Dependency Graph\n")
+        lines.append(self._generate_module_graph())
+        lines.append("")
+
+        # Layered architecture
+        layers = self._detect_layers()
+        if layers:
+            lines.append("## Architecture Layers\n")
+            for layer_name, modules in layers.items():
+                lines.append(f"### {layer_name}\n")
+                for mod in modules:
+                    lines.append(f"- `{mod}`")
+                lines.append("")
+
+        # Key classes
+        lines.append("## Key Classes\n")
+        lines.append(self._generate_class_diagram())
+        lines.append("")
+
+        # Patterns detected
+        if self.result.patterns:
+            lines.append("## Detected Patterns\n")
+            for pattern in self.result.patterns:
+                lines.append(
+                    f"- **{pattern.name}** ({pattern.type}) — "
+                    f"confidence: {pattern.confidence:.0%}, "
+                    f"functions: {', '.join(f'`{f}`' for f in pattern.functions[:5])}"
+                )
+            lines.append("")
+
+        # Entry points
+        if self.result.entry_points:
+            lines.append("## Entry Points\n")
+            for ep in self.result.entry_points:
+                func = self.result.functions.get(ep)
+                if func:
+                    doc = f" — {func.docstring.splitlines()[0]}" if func.docstring else ""
+                    lines.append(f"- `{ep}`{doc}")
+                else:
+                    lines.append(f"- `{ep}`")
+            lines.append("")
+
+        # Metrics summary
+        lines.append("## Metrics Summary\n")
+        lines.append(self._generate_metrics_table())
+
+        return "\n".join(lines)
+
+    def _generate_module_graph(self) -> str:
+        """Generate Mermaid module dependency graph."""
+        lines = ["```mermaid", "graph LR"]
+
+        # Build dependency edges from module imports
+        edges: Set[tuple] = set()
+        for mod_name, mod_info in self.result.modules.items():
+            short_name = mod_name.split(".")[-1]
+            for imp in mod_info.imports:
+                # Only show internal dependencies
+                imp_module = imp.split(".")[0] if "." in imp else imp
+                for other_mod in self.result.modules:
+                    other_short = other_mod.split(".")[-1]
+                    if imp_module in other_mod and mod_name != other_mod:
+                        edges.add((short_name, other_short))
+
+        for src, tgt in sorted(edges):
+            lines.append(f"    {src} --> {tgt}")
+
+        if not edges:
+            lines.append("    note[No internal dependencies detected]")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def _generate_class_diagram(self) -> str:
+        """Generate Mermaid class diagram for key classes."""
+        lines = ["```mermaid", "classDiagram"]
+
+        # Show top classes by method count
+        top_classes = sorted(
+            self.result.classes.values(),
+            key=lambda c: len(c.methods),
+            reverse=True,
+        )[:15]
+
+        for cls in top_classes:
+            lines.append(f"    class {cls.name} {{")
+            methods = cls.methods[:8]
+            for method_name in methods:
+                func = self.result.functions.get(
+                    f"{cls.qualified_name}.{method_name}"
+                ) or self.result.functions.get(method_name)
+                if func:
+                    args = ", ".join(func.args[:3])
+                    ret = func.returns or "None"
+                    prefix = "-" if func.is_private else "+"
+                    lines.append(f"        {prefix}{func.name}({args}) {ret}")
+                else:
+                    lines.append(f"        +{method_name}()")
+            if len(cls.methods) > 8:
+                lines.append(f"        ... +{len(cls.methods) - 8} more")
+            lines.append("    }")
+
+            # Inheritance
+            for base in cls.bases:
+                if base in [c.name for c in top_classes]:
+                    lines.append(f"    {base} <|-- {cls.name}")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def _detect_layers(self) -> Dict[str, List[str]]:
+        """Detect architectural layers from module names."""
+        layers: Dict[str, List[str]] = {}
+        layer_keywords = {
+            "Core": ["core", "base", "common", "utils", "lib"],
+            "API / CLI": ["cli", "api", "rest", "routes", "views", "endpoints"],
+            "Analysis": ["analysis", "analyzer", "parser", "scanner", "detector"],
+            "Export / Output": ["export", "output", "format", "render", "template"],
+            "Config": ["config", "settings", "constants"],
+            "Tests": ["test", "tests", "spec"],
+        }
+
+        for mod_name in sorted(self.result.modules.keys()):
+            lower = mod_name.lower()
+            assigned = False
+            for layer, keywords in layer_keywords.items():
+                if any(kw in lower for kw in keywords):
+                    layers.setdefault(layer, []).append(mod_name)
+                    assigned = True
+                    break
+            if not assigned:
+                layers.setdefault("Other", []).append(mod_name)
+
+        return {k: v for k, v in layers.items() if v}
+
+    def _generate_metrics_table(self) -> str:
+        """Generate metrics summary table."""
+        stats = self.result.stats or {}
+        lines = [
+            "| Metric | Value |",
+            "|--------|-------|",
+            f"| Modules | {len(self.result.modules)} |",
+            f"| Functions | {len(self.result.functions)} |",
+            f"| Classes | {len(self.result.classes)} |",
+            f"| CFG Nodes | {stats.get('nodes_created', len(self.result.nodes))} |",
+            f"| Patterns | {len(self.result.patterns)} |",
+        ]
+
+        # Average complexity
+        complexities = [
+            f.complexity.get("cyclomatic", 0)
+            for f in self.result.functions.values()
+            if f.complexity.get("cyclomatic", 0) > 0
+        ]
+        if complexities:
+            avg = round(sum(complexities) / len(complexities), 1)
+            lines.append(f"| Avg Complexity | {avg} |")
+
+        if stats.get("analysis_time_seconds"):
+            lines.append(f"| Analysis Time | {stats['analysis_time_seconds']}s |")
+
+        lines.append("")
+        return "\n".join(lines)

code2docs/generators/changelog_gen.py

@@ -0,0 +1,121 @@
+"""Changelog generator from git log and API diff."""
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from code2llm.core.models import AnalysisResult
+
+from ..config import Code2DocsConfig
+
+
+@dataclass
+class ChangelogEntry:
+    """A single changelog entry."""
+    date: str
+    hash: str
+    author: str
+    message: str
+    type: str = "other"  # feat, fix, refactor, docs, test, chore, other
+
+
+class ChangelogGenerator:
+    """Generate CHANGELOG.md from git log and analysis diff."""
+
+    CONVENTIONAL_TYPES = {
+        "feat": "Features",
+        "fix": "Bug Fixes",
+        "refactor": "Refactoring",
+        "docs": "Documentation",
+        "test": "Tests",
+        "perf": "Performance",
+        "chore": "Chores",
+        "ci": "CI/CD",
+        "style": "Style",
+        "build": "Build",
+    }
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+
+    def generate(self, project_path: Optional[str] = None, max_entries: int = 100) -> str:
+        """Generate changelog content from git log."""
+        project = Path(project_path or self.result.project_path)
+
+        entries = self._get_git_log(project, max_entries)
+        if not entries:
+            return "# Changelog\n\nNo git history available.\n"
+
+        grouped = self._group_by_type(entries)
+        return self._render(grouped)
+
+    def _get_git_log(self, project_path: Path, max_entries: int) -> List[ChangelogEntry]:
+        """Extract git log entries."""
+        try:
+            result = subprocess.run(
+                ["git", "log", f"--max-count={max_entries}",
+                 "--format=%H|%ad|%an|%s", "--date=short"],
+                cwd=str(project_path),
+                capture_output=True, text=True, timeout=10,
+            )
+            if result.returncode != 0:
+                return []
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return []
+
+        entries = []
+        for line in result.stdout.strip().splitlines():
+            parts = line.split("|", 3)
+            if len(parts) == 4:
+                entry = ChangelogEntry(
+                    hash=parts[0][:8],
+                    date=parts[1],
+                    author=parts[2],
+                    message=parts[3],
+                    type=self._classify_message(parts[3]),
+                )
+                entries.append(entry)
+
+        return entries
+
+    def _classify_message(self, message: str) -> str:
+        """Classify commit message by conventional commit type."""
+        lower = message.lower()
+        for prefix in self.CONVENTIONAL_TYPES:
+            if lower.startswith(f"{prefix}:") or lower.startswith(f"{prefix}("):
+                return prefix
+        return "other"
+
+    def _group_by_type(self, entries: List[ChangelogEntry]) -> Dict[str, List[ChangelogEntry]]:
+        """Group entries by type."""
+        grouped: Dict[str, List[ChangelogEntry]] = {}
+        for entry in entries:
+            grouped.setdefault(entry.type, []).append(entry)
+        return grouped
+
+    def _render(self, grouped: Dict[str, List[ChangelogEntry]]) -> str:
+        """Render grouped changelog to Markdown."""
+        lines = ["# Changelog\n"]
+
+        # Show by type
+        for type_key, type_label in self.CONVENTIONAL_TYPES.items():
+            entries = grouped.get(type_key, [])
+            if entries:
+                lines.append(f"## {type_label}\n")
+                for entry in entries:
+                    lines.append(
+                        f"- {entry.message} (`{entry.hash}` — {entry.date})"
+                    )
+                lines.append("")
+
+        # Other
+        other = grouped.get("other", [])
+        if other:
+            lines.append("## Other\n")
+            for entry in other:
+                lines.append(f"- {entry.message} (`{entry.hash}` — {entry.date})")
+            lines.append("")
+
+        return "\n".join(lines)

code2docs/generators/examples_gen.py

@@ -0,0 +1,194 @@
+"""Auto-generate usage examples from public signatures and entry points."""
+
+from pathlib import Path
+from typing import Dict, List
+
+from code2llm.core.models import AnalysisResult, FunctionInfo, ClassInfo
+
+from ..config import Code2DocsConfig
+
+
+class ExamplesGenerator:
+    """Generate examples/ — usage examples from public API signatures."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+
+    def generate_all(self) -> Dict[str, str]:
+        """Generate all example files. Returns {filename: content}."""
+        files: Dict[str, str] = {}
+
+        # Basic usage example
+        files["basic_usage.py"] = self._generate_basic_usage()
+
+        # Entry-point examples
+        if self.config.examples.from_entry_points and self.result.entry_points:
+            files["entry_points.py"] = self._generate_entry_point_examples()
+
+        # Class-based examples for major classes
+        major_classes = self._get_major_classes()
+        if major_classes:
+            files["class_examples.py"] = self._generate_class_examples(major_classes)
+
+        return files
+
+    def _generate_basic_usage(self) -> str:
+        """Generate basic_usage.py example."""
+        project_name = self.config.project_name or Path(self.result.project_path).name
+        lines: List[str] = [
+            f'"""Basic usage of {project_name}."""',
+            "",
+        ]
+
+        # Find importable public classes and functions
+        public_classes = [
+            c for c in self.result.classes.values()
+            if not c.name.startswith("_")
+        ]
+        public_functions = [
+            f for f in self.result.functions.values()
+            if not f.is_private and not f.is_method and not f.name.startswith("_")
+        ]
+
+        # Generate import statements
+        imported = set()
+        for cls in public_classes[:5]:
+            mod = cls.module or project_name
+            lines.append(f"from {mod} import {cls.name}")
+            imported.add(cls.name)
+
+        for func in public_functions[:5]:
+            if func.name not in imported:
+                mod = func.module or project_name
+                lines.append(f"from {mod} import {func.name}")
+                imported.add(func.name)
+
+        if not imported:
+            lines.append(f"import {project_name}")
+
+        lines.append("")
+        lines.append("")
+
+        # Generate usage examples
+        if public_classes:
+            cls = public_classes[0]
+            lines.append(f"# Create {cls.name} instance")
+            init_args = self._get_init_args(cls)
+            if init_args:
+                args_str = ", ".join(f"{a}=..." for a in init_args[:3])
+                lines.append(f"obj = {cls.name}({args_str})")
+            else:
+                lines.append(f"obj = {cls.name}()")
+            lines.append("")
+
+            # Show method calls
+            methods = self._get_public_methods(cls)
+            for method in methods[:3]:
+                args_str = ", ".join(f"{a}=..." for a in method.args if a != "self")
+                ret_comment = f"  # → {method.returns}" if method.returns else ""
+                lines.append(f"result = obj.{method.name}({args_str}){ret_comment}")
+
+        if public_functions:
+            lines.append("")
+            lines.append("# Standalone functions")
+            for func in public_functions[:5]:
+                args_str = ", ".join(f"{a}=..." for a in func.args[:4])
+                ret_comment = f"  # → {func.returns}" if func.returns else ""
+                lines.append(f"result = {func.name}({args_str}){ret_comment}")
+
+        lines.append("")
+        return "\n".join(lines)
+
+    def _generate_entry_point_examples(self) -> str:
+        """Generate examples based on entry points."""
+        project_name = self.config.project_name or Path(self.result.project_path).name
+        lines = [
+            f'"""Entry point examples for {project_name}."""',
+            "",
+        ]
+
+        for ep in self.result.entry_points[:5]:
+            func = self.result.functions.get(ep)
+            if func:
+                mod = func.module or project_name
+                lines.append(f"from {mod} import {func.name}")
+                lines.append("")
+                args_str = ", ".join(f"{a}=..." for a in func.args[:4])
+                lines.append(f"# Call entry point: {func.name}")
+                if func.docstring:
+                    lines.append(f"# {func.docstring.splitlines()[0]}")
+                lines.append(f"result = {func.name}({args_str})")
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _generate_class_examples(self, classes: List[ClassInfo]) -> str:
+        """Generate examples for major classes."""
+        project_name = self.config.project_name or Path(self.result.project_path).name
+        lines = [
+            f'"""Class usage examples for {project_name}."""',
+            "",
+        ]
+
+        for cls in classes[:5]:
+            mod = cls.module or project_name
+            lines.append(f"from {mod} import {cls.name}")
+
+        lines.append("")
+        lines.append("")
+
+        for cls in classes[:5]:
+            lines.append(f"# --- {cls.name} ---")
+            if cls.docstring:
+                lines.append(f"# {cls.docstring.splitlines()[0]}")
+
+            init_args = self._get_init_args(cls)
+            if init_args:
+                args_str = ", ".join(f"{a}=..." for a in init_args[:3])
+                lines.append(f"instance = {cls.name}({args_str})")
+            else:
+                lines.append(f"instance = {cls.name}()")
+
+            methods = self._get_public_methods(cls)
+            for m in methods[:3]:
+                args = [a for a in m.args if a != "self"]
+                args_str = ", ".join(f"{a}=..." for a in args[:3])
+                lines.append(f"instance.{m.name}({args_str})")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _get_major_classes(self) -> List[ClassInfo]:
+        """Get classes with most methods (likely most important)."""
+        classes = [c for c in self.result.classes.values() if not c.name.startswith("_")]
+        return sorted(classes, key=lambda c: len(c.methods), reverse=True)[:5]
+
+    def _get_init_args(self, cls: ClassInfo) -> List[str]:
+        """Get __init__ args for a class."""
+        for method_name in cls.methods:
+            if "__init__" in method_name:
+                for key in [method_name, f"{cls.qualified_name}.__init__"]:
+                    func = self.result.functions.get(key)
+                    if func:
+                        return [a for a in func.args if a != "self"]
+        return []
+
+    def _get_public_methods(self, cls: ClassInfo) -> List[FunctionInfo]:
+        """Get public methods of a class."""
+        methods = []
+        for method_name in cls.methods:
+            for key in [method_name, f"{cls.qualified_name}.{method_name}"]:
+                func = self.result.functions.get(key)
+                if func and not func.is_private and func.name != "__init__":
+                    methods.append(func)
+                    break
+        return methods
+
+    def write_all(self, output_dir: str, files: Dict[str, str]) -> None:
+        """Write all generated example files."""
+        out = Path(output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        for filename, content in files.items():
+            (out / filename).write_text(content, encoding="utf-8")