code2docs 0.1.1__py3-none-any.whl

code2docs/generators/module_docs_gen.py

@@ -0,0 +1,204 @@
+"""Per-module detailed documentation generator."""
+
+from pathlib import Path
+from typing import Dict, List
+
+from code2llm.core.models import AnalysisResult, ModuleInfo, FunctionInfo, ClassInfo
+
+from ..config import Code2DocsConfig
+
+
+class ModuleDocsGenerator:
+    """Generate docs/modules/ — detailed per-module documentation."""
+
+    def __init__(self, config: Code2DocsConfig, result: AnalysisResult):
+        self.config = config
+        self.result = result
+
+    def generate_all(self) -> Dict[str, str]:
+        """Generate documentation for all modules. Returns {filename: content}."""
+        files: Dict[str, str] = {}
+
+        for mod_name, mod_info in sorted(self.result.modules.items()):
+            safe_name = mod_name.replace(".", "_").replace("/", "_")
+            filename = f"{safe_name}.md"
+            files[filename] = self._generate_module(mod_name, mod_info)
+
+        return files
+
+    def _generate_module(self, mod_name: str, mod_info: ModuleInfo) -> str:
+        """Generate detailed documentation for a single module."""
+        lines: List[str] = []
+
+        # Header
+        lines.append(f"# {mod_name}\n")
+
+        # Source metadata
+        file_lines = self._count_file_lines(mod_info.file)
+        avg_cc = self._calc_module_avg_cc(mod_name)
+        meta_parts = [f"Source: `{mod_info.file}`"]
+        if file_lines:
+            meta_parts.append(f"{file_lines} lines")
+        if avg_cc:
+            meta_parts.append(f"CC avg: {avg_cc}")
+        lines.append(f"> {' | '.join(meta_parts)}\n")
+
+        # Overview (module docstring)
+        module_doc = self._get_module_docstring(mod_info)
+        if module_doc:
+            lines.append("## Overview\n")
+            lines.append(f"{module_doc}\n")
+
+        # Classes
+        module_classes = self._get_module_classes(mod_name)
+        if module_classes:
+            lines.append("## Classes\n")
+            for cls_name, cls_info in module_classes.items():
+                lines.append(f"### {cls_info.name}\n")
+                if cls_info.bases:
+                    lines.append(f"*Bases:* {', '.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")
+                    lines.append("| Method | Args | Returns | CC |")
+                    lines.append("|--------|------|---------|----|")
+                    for m in methods:
+                        args = ", ".join(m.args[:4])
+                        if len(m.args) > 4:
+                            args += ", ..."
+                        ret = m.returns or "—"
+                        cc = m.complexity.get("cyclomatic", "—")
+                        warn = " ⚠️" if isinstance(cc, (int, float)) and cc > 10 else ""
+                        lines.append(f"| `{m.name}` | `{args}` | `{ret}` | {cc}{warn} |")
+                    lines.append("")
+
+        # Functions
+        module_functions = self._get_module_functions(mod_name)
+        if module_functions:
+            lines.append("## Functions\n")
+            for func_name, func_info in module_functions.items():
+                args_str = ", ".join(func_info.args)
+                ret = f" → {func_info.returns}" if func_info.returns else ""
+                lines.append(f"### `{func_info.name}({args_str}){ret}`\n")
+                if func_info.docstring:
+                    lines.append(f"{func_info.docstring.strip()}\n")
+                if func_info.calls:
+                    lines.append(f"**Calls:** {', '.join(f'`{c}`' for c in func_info.calls[:10])}\n")
+                if func_info.called_by:
+                    lines.append(f"**Called by:** {', '.join(f'`{c}`' for c in func_info.called_by[:10])}\n")
+
+        # Dependencies
+        if mod_info.imports:
+            lines.append("## Dependencies\n")
+            internal = [i for i in mod_info.imports if not i.startswith(("os", "sys", "re", "json", "typing"))]
+            external = [i for i in mod_info.imports if i.startswith(("os", "sys", "re", "json", "typing"))]
+            if internal:
+                lines.append("**Internal imports:**")
+                for imp in sorted(internal):
+                    lines.append(f"- `{imp}`")
+                lines.append("")
+            if external:
+                lines.append("**Standard library:**")
+                for imp in sorted(external):
+                    lines.append(f"- `{imp}`")
+                lines.append("")
+
+        # Metrics table
+        metrics = self._get_module_metrics(mod_name, mod_info)
+        if metrics:
+            lines.append("## Metrics\n")
+            lines.append("| Metric | Value |")
+            lines.append("|--------|-------|")
+            for k, v in metrics.items():
+                lines.append(f"| {k} | {v} |")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _count_file_lines(self, file_path: str) -> int:
+        """Count lines in source file."""
+        try:
+            path = Path(file_path)
+            if path.exists():
+                return len(path.read_text(encoding="utf-8").splitlines())
+        except (OSError, UnicodeDecodeError):
+            pass
+        return 0
+
+    def _calc_module_avg_cc(self, mod_name: str) -> float:
+        """Calculate average cyclomatic complexity for module functions."""
+        complexities = []
+        for func in self.result.functions.values():
+            if func.module == mod_name:
+                cc = func.complexity.get("cyclomatic", 0)
+                if cc > 0:
+                    complexities.append(cc)
+        return round(sum(complexities) / len(complexities), 1) if complexities else 0.0
+
+    def _get_module_docstring(self, mod_info: ModuleInfo) -> str:
+        """Try to extract module-level docstring."""
+        try:
+            import ast
+            path = Path(mod_info.file)
+            if path.exists():
+                tree = ast.parse(path.read_text(encoding="utf-8"))
+                return ast.get_docstring(tree) or ""
+        except Exception:
+            pass
+        return ""
+
+    def _get_module_classes(self, mod_name: str) -> Dict[str, ClassInfo]:
+        return {
+            k: v for k, v in self.result.classes.items()
+            if v.module == mod_name or k.startswith(mod_name + ".")
+        }
+
+    def _get_module_functions(self, mod_name: str) -> Dict[str, FunctionInfo]:
+        return {
+            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
+        }
+
+    def _get_class_methods(self, cls_info: ClassInfo) -> List[FunctionInfo]:
+        methods = []
+        for method_name in cls_info.methods:
+            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
+
+    def _get_module_metrics(self, mod_name: str, mod_info: ModuleInfo) -> Dict[str, str]:
+        metrics = {}
+        lines = self._count_file_lines(mod_info.file)
+        if lines:
+            metrics["Lines"] = str(lines)
+        avg_cc = self._calc_module_avg_cc(mod_name)
+        if avg_cc:
+            metrics["Complexity (avg)"] = str(avg_cc)
+        metrics["Functions"] = str(len(mod_info.functions))
+        metrics["Classes"] = str(len(mod_info.classes))
+
+        # Fan-in / fan-out
+        fan_in = 0
+        fan_out = 0
+        for func in self.result.functions.values():
+            if func.module == mod_name:
+                fan_out += len(func.calls)
+                fan_in += len(func.called_by)
+        if fan_in:
+            metrics["Fan-in"] = str(fan_in)
+        if fan_out:
+            metrics["Fan-out"] = str(fan_out)
+
+        return metrics
+
+    def write_all(self, output_dir: str, files: Dict[str, str]) -> None:
+        """Write all generated module docs."""
+        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/readme_gen.py

@@ -0,0 +1,229 @@
+"""README.md generator from AnalysisResult."""
+
+import re
+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
+
+from ..config import Code2DocsConfig
+from ..analyzers.dependency_scanner import DependencyScanner
+from ..analyzers.endpoint_detector import EndpointDetector
+from ..formatters.badges import generate_badges
+from ..formatters.toc import generate_toc
+
+
+MARKER_START = "<!-- code2docs:start -->"
+MARKER_END = "<!-- code2docs:end -->"
+
+
+class ReadmeGenerator:
+    """Generate README.md from AnalysisResult."""
+
+    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(self) -> str:
+        """Generate full README content."""
+        sections = self.config.readme.sections
+        project_name = self.config.project_name or Path(self.result.project_path).name
+
+        context = self._build_context(project_name)
+
+        try:
+            template = self.env.get_template("readme.md.j2")
+            return template.render(**context, sections=sections)
+        except Exception:
+            # Fallback: build manually if template fails
+            return self._build_manual(project_name, sections, context)
+
+    def _build_context(self, project_name: str) -> Dict:
+        """Build template context from analysis result."""
+        # Dependencies
+        dep_scanner = DependencyScanner()
+        deps = dep_scanner.scan(self.result.project_path)
+
+        # Endpoints
+        endpoint_detector = EndpointDetector()
+        endpoints = endpoint_detector.detect(self.result, self.result.project_path)
+
+        # Public API
+        public_functions = {
+            k: v for k, v in self.result.functions.items()
+            if not v.is_private and not v.is_method
+        }
+        public_classes = {
+            k: v for k, v in self.result.classes.items()
+        }
+
+        # Entry points
+        entry_points = self.result.entry_points or []
+
+        # Metrics
+        stats = self.result.stats or {}
+        avg_complexity = self._calc_avg_complexity()
+
+        # Module tree
+        module_tree = self._build_module_tree()
+
+        return {
+            "project_name": project_name,
+            "project_path": self.result.project_path,
+            "badges": generate_badges(project_name, self.config.readme.badges, stats, deps),
+            "stats": stats,
+            "avg_complexity": avg_complexity,
+            "dependencies": deps,
+            "endpoints": endpoints,
+            "public_functions": public_functions,
+            "public_classes": public_classes,
+            "entry_points": entry_points,
+            "module_tree": module_tree,
+            "modules": self.result.modules,
+            "sync_markers": self.config.readme.sync_markers,
+        }
+
+    def _calc_avg_complexity(self) -> float:
+        """Calculate average cyclomatic complexity."""
+        complexities = []
+        for func in self.result.functions.values():
+            cc = func.complexity.get("cyclomatic", 0)
+            if cc > 0:
+                complexities.append(cc)
+        return round(sum(complexities) / len(complexities), 1) if complexities else 0.0
+
+    def _build_module_tree(self) -> str:
+        """Build text-based module tree."""
+        if not self.result.modules:
+            return ""
+
+        lines = []
+        sorted_modules = sorted(self.result.modules.keys())
+        for mod_name in sorted_modules:
+            mod = self.result.modules[mod_name]
+            prefix = "📦" if mod.is_package else "📄"
+            func_count = len(mod.functions)
+            class_count = len(mod.classes)
+            detail = []
+            if func_count:
+                detail.append(f"{func_count} functions")
+            if class_count:
+                detail.append(f"{class_count} classes")
+            detail_str = f" ({', '.join(detail)})" if detail else ""
+            lines.append(f"{prefix} `{mod_name}`{detail_str}")
+
+        return "\n".join(lines)
+
+    def _build_manual(self, project_name: str, sections: List[str], context: Dict) -> str:
+        """Fallback manual README builder."""
+        parts: List[str] = []
+
+        if context.get("sync_markers"):
+            parts.append(MARKER_START)
+
+        if "overview" in sections:
+            parts.append(f"# {project_name}\n")
+            if context.get("badges"):
+                parts.append(context["badges"] + "\n")
+            stats = context.get("stats", {})
+            if stats:
+                parts.append(
+                    f"> **{stats.get('functions_found', 0)}** functions | "
+                    f"**{stats.get('classes_found', 0)}** classes | "
+                    f"**{stats.get('files_processed', 0)}** files | "
+                    f"CC̄ = {context.get('avg_complexity', 0)}\n"
+                )
+
+        if "install" in sections:
+            deps = context.get("dependencies")
+            if deps and deps.install_command:
+                parts.append("## Installation\n")
+                parts.append(f"```bash\n{deps.install_command}\n```\n")
+                if deps.python_version:
+                    parts.append(f"Requires Python {deps.python_version}\n")
+
+        if "quickstart" in sections:
+            parts.append("## Quick Start\n")
+            entry_points = context.get("entry_points", [])
+            if entry_points:
+                parts.append("```python")
+                parts.append(f"# Entry points: {', '.join(entry_points[:3])}")
+                parts.append("```\n")
+
+        if "api" in sections:
+            parts.append("## API Overview\n")
+            for name, cls in list(context.get("public_classes", {}).items())[:20]:
+                doc = f" — {cls.docstring.splitlines()[0]}" if cls.docstring else ""
+                parts.append(f"- **`{cls.name}`**{doc}")
+            parts.append("")
+            for name, func in list(context.get("public_functions", {}).items())[:30]:
+                args_str = ", ".join(func.args[:5])
+                ret = f" → {func.returns}" if func.returns else ""
+                parts.append(f"- `{func.name}({args_str}){ret}`")
+            parts.append("")
+
+        if "structure" in sections:
+            tree = context.get("module_tree", "")
+            if tree:
+                parts.append("## Project Structure\n")
+                parts.append(tree + "\n")
+
+        if "endpoints" in sections:
+            endpoints = context.get("endpoints", [])
+            if endpoints:
+                parts.append("## Endpoints\n")
+                parts.append("| Method | Path | Function | Framework |")
+                parts.append("|--------|------|----------|-----------|")
+                for ep in endpoints:
+                    parts.append(f"| {ep.method} | `{ep.path}` | `{ep.function_name}` | {ep.framework} |")
+                parts.append("")
+
+        if context.get("sync_markers"):
+            parts.append(MARKER_END)
+
+        return "\n".join(parts)
+
+    def write(self, path: str, content: str) -> None:
+        """Write README, respecting sync markers if existing file has them."""
+        readme_path = Path(path)
+
+        if readme_path.exists():
+            existing = readme_path.read_text(encoding="utf-8")
+            if MARKER_START in existing and MARKER_END in existing:
+                # Replace only between markers
+                pattern = re.compile(
+                    re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END),
+                    re.DOTALL,
+                )
+                content = pattern.sub(content, existing)
+
+        readme_path.parent.mkdir(parents=True, exist_ok=True)
+        readme_path.write_text(content, encoding="utf-8")
+
+
+def generate_readme(project_path: str = "./", output: str = "README.md",
+                    sections: Optional[List[str]] = None, sync_markers: bool = True,
+                    config: Optional[Code2DocsConfig] = None) -> str:
+    """Convenience function to generate a README."""
+    from ..analyzers.project_scanner import ProjectScanner
+
+    config = config or Code2DocsConfig()
+    if sections:
+        config.readme.sections = sections
+    config.readme.sync_markers = sync_markers
+
+    scanner = ProjectScanner(config)
+    result = scanner.analyze(project_path)
+
+    gen = ReadmeGenerator(config, result)
+    content = gen.generate()
+    gen.write(output, content)
+    return content

code2docs/sync/__init__.py

@@ -0,0 +1,6 @@
+"""Sync — detect changes and selectively regenerate documentation."""
+
+from .differ import Differ
+from .updater import Updater
+
+__all__ = ["Differ", "Updater"]

code2docs/sync/differ.py

@@ -0,0 +1,125 @@
+"""Detect changes in source code for selective documentation regeneration."""
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..config import Code2DocsConfig
+
+STATE_FILE = ".code2docs.state"
+
+
+@dataclass
+class ChangeInfo:
+    """Describes a detected change."""
+    module: str
+    file: str
+    change_type: str  # added, modified, deleted
+    old_hash: str = ""
+    new_hash: str = ""
+
+    def __str__(self) -> str:
+        return f"[{self.change_type}] {self.module} ({self.file})"
+
+
+class Differ:
+    """Detect changes between current source and previous state."""
+
+    def __init__(self, config: Optional[Code2DocsConfig] = None):
+        self.config = config or Code2DocsConfig()
+
+    def detect_changes(self, project_path: str) -> List[ChangeInfo]:
+        """Compare current file hashes with saved state. Return list of changes."""
+        project = Path(project_path).resolve()
+        state_path = project / STATE_FILE
+
+        old_state = self._load_state(state_path)
+        new_state = self._compute_state(project)
+
+        changes: List[ChangeInfo] = []
+
+        # Detect modified and added
+        for filepath, new_hash in new_state.items():
+            old_hash = old_state.get(filepath, "")
+            if not old_hash:
+                changes.append(ChangeInfo(
+                    module=self._file_to_module(filepath, project),
+                    file=filepath,
+                    change_type="added",
+                    new_hash=new_hash,
+                ))
+            elif old_hash != new_hash:
+                changes.append(ChangeInfo(
+                    module=self._file_to_module(filepath, project),
+                    file=filepath,
+                    change_type="modified",
+                    old_hash=old_hash,
+                    new_hash=new_hash,
+                ))
+
+        # Detect deleted
+        for filepath, old_hash in old_state.items():
+            if filepath not in new_state:
+                changes.append(ChangeInfo(
+                    module=self._file_to_module(filepath, project),
+                    file=filepath,
+                    change_type="deleted",
+                    old_hash=old_hash,
+                ))
+
+        return changes
+
+    def save_state(self, project_path: str) -> None:
+        """Save current file hashes as state."""
+        project = Path(project_path).resolve()
+        state = self._compute_state(project)
+        state_path = project / STATE_FILE
+        state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+    def _load_state(self, state_path: Path) -> Dict[str, str]:
+        """Load previous state from file."""
+        if not state_path.exists():
+            return {}
+        try:
+            return json.loads(state_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _compute_state(self, project: Path) -> Dict[str, str]:
+        """Compute file hashes for all Python files in the project."""
+        state: Dict[str, str] = {}
+        ignore_patterns = self.config.sync.ignore if self.config else []
+
+        for py_file in project.rglob("*.py"):
+            rel = str(py_file.relative_to(project))
+
+            # Check ignore patterns
+            if any(pattern.rstrip("/") in rel for pattern in ignore_patterns):
+                continue
+
+            try:
+                content = py_file.read_bytes()
+                file_hash = hashlib.sha256(content).hexdigest()[:16]
+                state[rel] = file_hash
+            except OSError:
+                continue
+
+        return state
+
+    @staticmethod
+    def _file_to_module(filepath: str, project: Path) -> str:
+        """Convert file path to module name."""
+        p = Path(filepath)
+        if p.is_absolute():
+            try:
+                p = p.relative_to(project)
+            except ValueError:
+                pass
+        parts = list(p.parts)
+        if parts and parts[-1] == "__init__.py":
+            parts = parts[:-1]
+        elif parts:
+            parts[-1] = parts[-1].replace(".py", "")
+        return ".".join(parts)

code2docs/sync/updater.py

@@ -0,0 +1,77 @@
+"""Selectively regenerate documentation for changed modules."""
+
+from pathlib import Path
+from typing import List, Optional
+
+from ..config import Code2DocsConfig
+from .differ import ChangeInfo, Differ
+
+
+class Updater:
+    """Apply selective documentation updates based on detected changes."""
+
+    def __init__(self, config: Optional[Code2DocsConfig] = None):
+        self.config = config or Code2DocsConfig()
+
+    def apply(self, project_path: str, changes: List[ChangeInfo]) -> None:
+        """Regenerate documentation for changed modules."""
+        from ..analyzers.project_scanner import ProjectScanner
+        from ..generators.readme_gen import ReadmeGenerator
+        from ..generators.api_reference_gen import ApiReferenceGenerator
+        from ..generators.module_docs_gen import ModuleDocsGenerator
+
+        project = Path(project_path).resolve()
+
+        # Re-analyze project
+        scanner = ProjectScanner(self.config)
+        result = scanner.analyze(str(project))
+
+        changed_modules = {c.module for c in changes}
+
+        # Always regenerate README (it references all modules)
+        readme_gen = ReadmeGenerator(self.config, result)
+        readme_content = readme_gen.generate()
+        readme_gen.write(str(project / self.config.readme_output), readme_content)
+
+        # Regenerate API docs for changed modules
+        if self.config.docs.api_reference:
+            api_gen = ApiReferenceGenerator(self.config, result)
+            all_files = api_gen.generate_all()
+
+            # Filter to changed modules only
+            docs_dir = project / self.config.output / "api"
+            docs_dir.mkdir(parents=True, exist_ok=True)
+
+            # Always regenerate index
+            index_content = all_files.get("index.md", "")
+            if index_content:
+                (docs_dir / "index.md").write_text(index_content, encoding="utf-8")
+
+            for filename, content in all_files.items():
+                if filename == "index.md":
+                    continue
+                # Check if this file corresponds to a changed module
+                for mod in changed_modules:
+                    safe_mod = mod.replace(".", "_").replace("/", "_")
+                    if safe_mod in filename:
+                        (docs_dir / filename).write_text(content, encoding="utf-8")
+                        break
+
+        # Regenerate module docs for changed modules
+        if self.config.docs.module_docs:
+            mod_gen = ModuleDocsGenerator(self.config, result)
+            all_files = mod_gen.generate_all()
+
+            docs_dir = project / self.config.output / "modules"
+            docs_dir.mkdir(parents=True, exist_ok=True)
+
+            for filename, content in all_files.items():
+                for mod in changed_modules:
+                    safe_mod = mod.replace(".", "_").replace("/", "_")
+                    if safe_mod in filename:
+                        (docs_dir / filename).write_text(content, encoding="utf-8")
+                        break
+
+        # Save new state
+        differ = Differ(self.config)
+        differ.save_state(str(project))