code2docs 0.1.1__py3-none-any.whl

code2docs/__init__.py

@@ -0,0 +1,32 @@
+"""
+code2docs - Auto-generate and sync project documentation from source code.
+
+Uses code2llm's AnalysisResult to produce human-readable documentation:
+README.md, API references, module docs, examples, and architecture diagrams.
+"""
+
+__version__ = "0.1.1"
+__author__ = "Tom Sapletta"
+
+from .config import Code2DocsConfig
+
+__all__ = [
+    "Code2DocsConfig",
+    "generate_readme",
+    "generate_docs",
+    "analyze_and_document",
+]
+
+
+def __getattr__(name):
+    """Lazy import heavy modules on first access."""
+    if name == "generate_readme":
+        from .generators.readme_gen import generate_readme
+        return generate_readme
+    if name == "generate_docs":
+        from .generators import generate_docs
+        return generate_docs
+    if name == "analyze_and_document":
+        from .analyzers.project_scanner import analyze_and_document
+        return analyze_and_document
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

code2docs/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running code2docs as: python -m code2docs"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

code2docs/analyzers/__init__.py

@@ -0,0 +1,13 @@
+"""Analyzers — adapters to code2llm and custom detectors."""
+
+from .project_scanner import ProjectScanner
+from .endpoint_detector import EndpointDetector
+from .docstring_extractor import DocstringExtractor
+from .dependency_scanner import DependencyScanner
+
+__all__ = [
+    "ProjectScanner",
+    "EndpointDetector",
+    "DocstringExtractor",
+    "DependencyScanner",
+]

code2docs/analyzers/dependency_scanner.py

@@ -0,0 +1,159 @@
+"""Scan project dependencies from requirements.txt, pyproject.toml, setup.py."""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None  # type: ignore
+
+
+@dataclass
+class DependencyInfo:
+    """Information about a project dependency."""
+    name: str
+    version_spec: str = ""
+    optional: bool = False
+    group: str = "main"
+
+
+@dataclass
+class ProjectDependencies:
+    """All detected project dependencies."""
+    python_version: str = ""
+    dependencies: List[DependencyInfo] = field(default_factory=list)
+    dev_dependencies: List[DependencyInfo] = field(default_factory=list)
+    optional_groups: Dict[str, List[DependencyInfo]] = field(default_factory=dict)
+    install_command: str = "pip install ."
+    source_file: str = ""
+
+
+class DependencyScanner:
+    """Scan and parse project dependency files."""
+
+    def scan(self, project_path: str) -> ProjectDependencies:
+        """Scan project for dependency information."""
+        project = Path(project_path)
+        deps = ProjectDependencies()
+
+        # Priority: pyproject.toml > setup.py > requirements.txt
+        pyproject = project / "pyproject.toml"
+        if pyproject.exists():
+            deps = self._parse_pyproject(pyproject)
+            deps.source_file = "pyproject.toml"
+            return deps
+
+        setup_py = project / "setup.py"
+        if setup_py.exists():
+            deps = self._parse_setup_py(setup_py)
+            deps.source_file = "setup.py"
+            return deps
+
+        req_txt = project / "requirements.txt"
+        if req_txt.exists():
+            deps = self._parse_requirements_txt(req_txt)
+            deps.source_file = "requirements.txt"
+            return deps
+
+        return deps
+
+    def _parse_pyproject(self, path: Path) -> ProjectDependencies:
+        """Parse pyproject.toml for dependencies."""
+        deps = ProjectDependencies()
+
+        if tomllib is None:
+            # Fallback: regex-based parsing
+            return self._parse_pyproject_regex(path)
+
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+        project = data.get("project", {})
+        deps.python_version = project.get("requires-python", "")
+
+        # Main dependencies
+        for dep_str in project.get("dependencies", []):
+            deps.dependencies.append(self._parse_dep_string(dep_str))
+
+        # Optional dependencies
+        for group, dep_list in project.get("optional-dependencies", {}).items():
+            group_deps = [self._parse_dep_string(d) for d in dep_list]
+            for d in group_deps:
+                d.optional = True
+                d.group = group
+            deps.optional_groups[group] = group_deps
+            if group == "dev":
+                deps.dev_dependencies = group_deps
+
+        # Install command
+        name = project.get("name", "")
+        if name:
+            deps.install_command = f"pip install {name}"
+
+        return deps
+
+    def _parse_pyproject_regex(self, path: Path) -> ProjectDependencies:
+        """Fallback regex-based pyproject.toml parser."""
+        deps = ProjectDependencies()
+        content = path.read_text(encoding="utf-8")
+
+        # Extract dependencies array
+        dep_match = re.search(r'dependencies\s*=\s*\[(.*?)\]', content, re.DOTALL)
+        if dep_match:
+            for dep_str in re.findall(r'"([^"]+)"', dep_match.group(1)):
+                deps.dependencies.append(self._parse_dep_string(dep_str))
+
+        # Extract python version
+        py_match = re.search(r'requires-python\s*=\s*"([^"]+)"', content)
+        if py_match:
+            deps.python_version = py_match.group(1)
+
+        return deps
+
+    def _parse_setup_py(self, path: Path) -> ProjectDependencies:
+        """Parse setup.py for dependencies (regex-based, no exec)."""
+        deps = ProjectDependencies()
+        content = path.read_text(encoding="utf-8")
+
+        # install_requires
+        match = re.search(r'install_requires\s*=\s*\[(.*?)\]', content, re.DOTALL)
+        if match:
+            for dep_str in re.findall(r'"([^"]+)"', match.group(1)):
+                deps.dependencies.append(self._parse_dep_string(dep_str))
+
+        # python_requires
+        py_match = re.search(r'python_requires\s*=\s*"([^"]+)"', content)
+        if py_match:
+            deps.python_version = py_match.group(1)
+
+        return deps
+
+    def _parse_requirements_txt(self, path: Path) -> ProjectDependencies:
+        """Parse requirements.txt."""
+        deps = ProjectDependencies()
+
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or line.startswith("-"):
+                continue
+            deps.dependencies.append(self._parse_dep_string(line))
+
+        deps.install_command = "pip install -r requirements.txt"
+        return deps
+
+    @staticmethod
+    def _parse_dep_string(dep_str: str) -> DependencyInfo:
+        """Parse a dependency string like 'package>=1.0'."""
+        match = re.match(r'^([a-zA-Z0-9_-]+)\s*(.*)', dep_str.strip())
+        if match:
+            return DependencyInfo(
+                name=match.group(1),
+                version_spec=match.group(2).strip(),
+            )
+        return DependencyInfo(name=dep_str.strip())

code2docs/analyzers/docstring_extractor.py

@@ -0,0 +1,111 @@
+"""Extract and analyze docstrings from source code."""
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from code2llm.core.models import AnalysisResult, FunctionInfo, ClassInfo
+
+
+@dataclass
+class DocstringInfo:
+    """Parsed docstring with sections."""
+    raw: str
+    summary: str = ""
+    description: str = ""
+    params: Dict[str, str] = field(default_factory=dict)
+    returns: str = ""
+    raises: List[str] = field(default_factory=list)
+    examples: List[str] = field(default_factory=list)
+
+
+class DocstringExtractor:
+    """Extract and parse docstrings from AnalysisResult."""
+
+    def extract_all(self, result: AnalysisResult) -> Dict[str, DocstringInfo]:
+        """Extract docstrings for all functions and classes."""
+        docs: Dict[str, DocstringInfo] = {}
+
+        for name, func in result.functions.items():
+            if func.docstring:
+                docs[name] = self.parse(func.docstring)
+
+        for name, cls in result.classes.items():
+            if cls.docstring:
+                docs[name] = self.parse(cls.docstring)
+
+        return docs
+
+    def parse(self, docstring: str) -> DocstringInfo:
+        """Parse a docstring into structured sections."""
+        if not docstring:
+            return DocstringInfo(raw="")
+
+        lines = docstring.strip().splitlines()
+        info = DocstringInfo(raw=docstring)
+
+        if lines:
+            info.summary = lines[0].strip()
+
+        # Simple parser for Google/Numpy/Sphinx styles
+        current_section = "description"
+        desc_lines: List[str] = []
+        param_lines: List[Tuple[str, str]] = []
+
+        for line in lines[1:]:
+            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(">>>"):
+                    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()
+            elif current_section == "returns" and stripped:
+                info.returns = stripped
+            elif current_section == "raises" and stripped:
+                info.raises.append(stripped)
+            elif current_section == "examples" and stripped:
+                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."""
+        total_funcs = len(result.functions)
+        total_classes = len(result.classes)
+        documented_funcs = sum(1 for f in result.functions.values() if f.docstring)
+        documented_classes = sum(1 for c in result.classes.values() if c.docstring)
+
+        return {
+            "functions_total": total_funcs,
+            "functions_documented": documented_funcs,
+            "functions_coverage": (documented_funcs / total_funcs * 100) if total_funcs else 0,
+            "classes_total": total_classes,
+            "classes_documented": documented_classes,
+            "classes_coverage": (documented_classes / total_classes * 100) if total_classes else 0,
+            "overall_coverage": (
+                (documented_funcs + documented_classes)
+                / (total_funcs + total_classes)
+                * 100
+            ) if (total_funcs + total_classes) else 0,
+        }

code2docs/analyzers/endpoint_detector.py

@@ -0,0 +1,116 @@
+"""Detect web framework endpoints (Flask, FastAPI, Django) from AST analysis."""
+
+import ast
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from code2llm.core.models import AnalysisResult, FunctionInfo
+
+
+@dataclass
+class Endpoint:
+    """Represents a detected web endpoint."""
+    method: str  # GET, POST, PUT, DELETE, etc.
+    path: str
+    function_name: str
+    file: str
+    line: int
+    framework: str  # flask, fastapi, django
+    docstring: Optional[str] = None
+    params: List[str] = field(default_factory=list)
+    return_type: Optional[str] = None
+
+
+class EndpointDetector:
+    """Detects web endpoints from decorator patterns in source code."""
+
+    FLASK_PATTERNS = re.compile(
+        r'@(?:app|blueprint|bp)\.(route|get|post|put|delete|patch)\s*\(\s*["\']([^"\']+)["\']'
+    )
+    FASTAPI_PATTERNS = re.compile(
+        r'@(?:app|router)\.(get|post|put|delete|patch|options|head)\s*\(\s*["\']([^"\']+)["\']'
+    )
+    DJANGO_URL_PATTERN = re.compile(
+        r'(?:path|re_path|url)\s*\(\s*["\']([^"\']+)["\']'
+    )
+
+    def detect(self, result: AnalysisResult, project_path: str) -> List[Endpoint]:
+        """Detect all endpoints from the analysis result."""
+        endpoints: List[Endpoint] = []
+
+        for qualified_name, func_info in result.functions.items():
+            file_path = func_info.file
+            if not file_path:
+                continue
+
+            # Check decorators for route patterns
+            for decorator in func_info.decorators:
+                endpoint = self._parse_decorator(decorator, func_info)
+                if endpoint:
+                    endpoints.append(endpoint)
+
+        # Also scan for Django URL patterns in urls.py files
+        endpoints.extend(self._scan_django_urls(project_path))
+
+        return endpoints
+
+    def _parse_decorator(self, decorator: str, func: FunctionInfo) -> Optional[Endpoint]:
+        """Try to parse a route decorator string."""
+        # Flask patterns
+        match = self.FLASK_PATTERNS.search(decorator)
+        if match:
+            method = match.group(1).upper()
+            if method == "ROUTE":
+                method = "GET"
+            return Endpoint(
+                method=method,
+                path=match.group(2),
+                function_name=func.name,
+                file=func.file,
+                line=func.line,
+                framework="flask",
+                docstring=func.docstring,
+                params=func.args,
+                return_type=func.returns,
+            )
+
+        # FastAPI patterns
+        match = self.FASTAPI_PATTERNS.search(decorator)
+        if match:
+            return Endpoint(
+                method=match.group(1).upper(),
+                path=match.group(2),
+                function_name=func.name,
+                file=func.file,
+                line=func.line,
+                framework="fastapi",
+                docstring=func.docstring,
+                params=func.args,
+                return_type=func.returns,
+            )
+
+        return None
+
+    def _scan_django_urls(self, project_path: str) -> List[Endpoint]:
+        """Scan urls.py files for Django URL patterns."""
+        endpoints: List[Endpoint] = []
+        project = Path(project_path)
+
+        for urls_file in project.rglob("urls.py"):
+            try:
+                source = urls_file.read_text(encoding="utf-8")
+                for match in self.DJANGO_URL_PATTERN.finditer(source):
+                    endpoints.append(Endpoint(
+                        method="GET",
+                        path=match.group(1),
+                        function_name="",
+                        file=str(urls_file),
+                        line=source[:match.start()].count("\n") + 1,
+                        framework="django",
+                    ))
+            except (OSError, UnicodeDecodeError):
+                continue
+
+        return endpoints

code2docs/analyzers/project_scanner.py

@@ -0,0 +1,45 @@
+"""Wrapper around code2llm's ProjectAnalyzer for documentation purposes."""
+
+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 ..config import Code2DocsConfig
+
+
+class ProjectScanner:
+    """Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults."""
+
+    def __init__(self, config: Optional[Code2DocsConfig] = None):
+        self.config = config or Code2DocsConfig()
+        self._llm_config = self._build_llm_config()
+
+    def _build_llm_config(self) -> Config:
+        """Create code2llm Config tuned for documentation generation."""
+        config = Config(
+            mode="static",
+            verbose=self.config.verbose,
+        )
+        config.filters.exclude_tests = self.config.exclude_tests
+        config.filters.skip_private = self.config.skip_private
+        # Keep properties and accessors visible for docs
+        config.filters.skip_properties = False
+        config.filters.skip_accessors = False
+        # Enable pattern detection for architecture docs
+        config.performance.skip_pattern_detection = False
+        config.performance.parallel_enabled = True
+        return config
+
+    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)
+
+
+def analyze_and_document(project_path: str, config: Optional[Code2DocsConfig] = None) -> AnalysisResult:
+    """Convenience function: analyze a project in one call."""
+    scanner = ProjectScanner(config)
+    return scanner.analyze(project_path)