code2docs 3.0.27__py3-none-any.whl → 3.0.29__py3-none-any.whl

code2docs/__init__.py

@@ -5,7 +5,7 @@ Uses code2llm's AnalysisResult to produce human-readable documentation:
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = '3.0.27'
+__version__ = '3.0.29'
 __author__ = 'Tom Sapletta'
 __all__ = ['Code2DocsConfig', 'generate_readme', 'generate_docs', 'analyze_and_document']
 

code2docs/generators/_registry_adapters.py

@@ -260,31 +260,43 @@ class IndexHtmlAdapter(BaseGenerator):
 
     def _generate_html(self, ctx: GenerateContext) -> str:
         project_name = self.config.project_name or ctx.project.name
-        repo_url = self.config.repo_url
-        files = []
-        if (ctx.docs_dir / 'README.md').exists():
-            files.append(('README.md', 'Project Overview', '📖'))
-        if (ctx.docs_dir / 'getting-started.md').exists():
-            files.append(('getting-started.md', 'Getting Started', '🚀'))
-        if (ctx.docs_dir / 'api.md').exists():
-            files.append(('api.md', 'API Reference', '📚'))
-        if (ctx.docs_dir / 'modules.md').exists():
-            files.append(('modules.md', 'Module Documentation', '📦'))
-        if (ctx.docs_dir / 'architecture.md').exists():
-            files.append(('architecture.md', 'Architecture', '🏗️'))
-        if (ctx.docs_dir / 'dependency-graph.md').exists():
-            files.append(('dependency-graph.md', 'Dependency Graph', '🔗'))
-        if (ctx.docs_dir / 'coverage.md').exists():
-            files.append(('coverage.md', 'Code Coverage', '📊'))
-        if (ctx.docs_dir / 'api-changelog.md').exists():
-            files.append(('api-changelog.md', 'API Changelog', '📝'))
-        if (ctx.docs_dir / 'configuration.md').exists():
-            files.append(('configuration.md', 'Configuration', '⚙️'))
-        if (ctx.docs_dir / 'CONTRIBUTING.md').exists():
-            files.append(('CONTRIBUTING.md', 'Contributing Guide', '🤝'))
-        if (ctx.docs_dir / 'examples').is_dir():
+        files = self._collect_doc_files(ctx.docs_dir)
+        github_link = self._build_github_link(self.config.repo_url)
+        files_html = self._build_files_html(files)
+        return self._build_html_template(project_name, github_link, files_html)
+
+    def _collect_doc_files(self, docs_dir: Path) -> list:
+        """Collect existing documentation files with their display info."""
+        doc_files = [
+            ('README.md', 'Project Overview', '📖'),
+            ('getting-started.md', 'Getting Started', '🚀'),
+            ('api.md', 'API Reference', '📚'),
+            ('modules.md', 'Module Documentation', '📦'),
+            ('architecture.md', 'Architecture', '🏗️'),
+            ('dependency-graph.md', 'Dependency Graph', '🔗'),
+            ('coverage.md', 'Code Coverage', '📊'),
+            ('api-changelog.md', 'API Changelog', '📝'),
+            ('configuration.md', 'Configuration', '⚙️'),
+            ('CONTRIBUTING.md', 'Contributing Guide', '🤝'),
+        ]
+        files = [(href, title, icon) for href, title, icon in doc_files if (docs_dir / href).exists()]
+        if (docs_dir / 'examples').is_dir():
             files.append(('examples/', 'Examples', '💡'))
-        github_link = f'<a href="{repo_url}" class="github-link" target="_blank" rel="noopener">View on GitHub</a>' if repo_url else ''
-        files_html = '\n'.join((f'<a href="{href}" class="doc-card"><span class="icon">{icon}</span><span class="title">{title}</span></a>' for href, title, icon in files))
+        return files
+
+    def _build_github_link(self, repo_url: str) -> str:
+        """Build GitHub link HTML if repo_url is available."""
+        if not repo_url:
+            return ''
+        return f'<a href="{repo_url}" class="github-link" target="_blank" rel="noopener">View on GitHub</a>'
+
+    def _build_files_html(self, files: list) -> str:
+        """Build HTML for file cards."""
+        return '\n'.join(
+            f'<a href="{href}" class="doc-card"><span class="icon">{icon}</span><span class="title">{title}</span></a>'
+            for href, title, icon in files
+        )
+
+    def _build_html_template(self, project_name: str, github_link: str, files_html: str) -> str:
         return f'<!DOCTYPE html>\n<html lang="en">\n<head>\n    <meta charset="UTF-8">\n    <meta name="viewport" content="width=device-width, initial-scale=1.0">\n    <title>{project_name} - Documentation</title>\n    <style>\n        * {{ margin: 0; padding: 0; box-sizing: border-box; }}\n        body {{\n            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;\n            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n            min-height: 100vh;\n            padding: 40px 20px;\n        }}\n        .container {{\n            max-width: 900px;\n            margin: 0 auto;\n        }}\n        .header {{\n            text-align: center;\n            margin-bottom: 40px;\n            color: white;\n        }}\n        .header h1 {{\n            font-size: 2.5rem;\n            margin-bottom: 10px;\n            text-shadow: 0 2px 4px rgba(0,0,0,0.2);\n        }}\n        .header p {{\n            font-size: 1.1rem;\n            opacity: 0.9;\n        }}\n        .github-link {{\n            display: inline-block;\n            margin-top: 15px;\n            padding: 10px 20px;\n            background: rgba(255,255,255,0.2);\n            color: white;\n            text-decoration: none;\n            border-radius: 25px;\n            transition: background 0.3s;\n        }}\n        .github-link:hover {{ background: rgba(255,255,255,0.3); }}\n        .docs-grid {{\n            display: grid;\n            grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));\n            gap: 20px;\n        }}\n        .doc-card {{\n            background: white;\n            border-radius: 12px;\n            padding: 25px;\n            text-decoration: none;\n            color: #333;\n            box-shadow: 0 4px 15px rgba(0,0,0,0.1);\n            transition: transform 0.2s, box-shadow 0.2s;\n            display: flex;\n            align-items: center;\n            gap: 15px;\n        }}\n        .doc-card:hover {{\n            transform: translateY(-3px);\n            box-shadow: 0 8px 25px rgba(0,0,0,0.15);\n        }}\n        .doc-card .icon {{\n            font-size: 2rem;\n            flex-shrink: 0;\n        }}\n        .doc-card .title {{\n            font-size: 1.1rem;\n            font-weight: 600;\n        }}\n        .footer {{\n            text-align: center;\n            margin-top: 40px;\n            color: rgba(255,255,255,0.7);\n            font-size: 0.9rem;\n        }}\n        @media (max-width: 600px) {{\n            .header h1 {{ font-size: 1.8rem; }}\n            .docs-grid {{ grid-template-columns: 1fr; }}\n        }}\n    </style>\n</head>\n<body>\n    <div class="container">\n        <div class="header">\n            <h1>{project_name}</h1>\n            <p>Generated Documentation</p>\n            {github_link}\n        </div>\n        <div class="docs-grid">\n            {files_html}\n        </div>\n        <div class="footer">\n            Generated with <a href="https://github.com/wronai/code2docs" style="color: rgba(255,255,255,0.9);">code2docs</a>\n        </div>\n    </div>\n</body>\n</html>'
 ALL_ADAPTERS = [ReadmeGeneratorAdapter, ApiReferenceAdapter, ModuleDocsAdapter, ArchitectureAdapter, DepGraphAdapter, CoverageAdapter, ApiChangelogAdapter, ExamplesAdapter, GettingStartedAdapter, ConfigDocsAdapter, ContributingAdapter, MkDocsAdapter, Code2LlmAdapter, OrgReadmeAdapter, IndexHtmlAdapter]

code2docs/generators/api_reference_gen.py

@@ -88,56 +88,74 @@ class ApiReferenceGenerator:
         heading = f"### `{mod_name}` {src}" if src else f"### `{mod_name}`"
         lines = [f"{heading}\n"]
 
-        # Classes table
-        module_classes = {
+        module_classes = self._get_module_classes(mod_name)
+        if module_classes:
+            lines.extend(self._render_classes_table(module_classes))
+            lines.extend(self._render_class_methods(module_classes))
+
+        module_functions = self._get_module_functions(mod_name)
+        if module_functions:
+            lines.extend(self._render_functions_table(module_functions))
+
+        return "\n".join(lines)
+
+    def _get_module_classes(self, mod_name: str) -> Dict[str, ClassInfo]:
+        """Get all public classes for a module."""
+        return {
             k: v for k, v in self.result.classes.items()
             if (v.module == mod_name or k.startswith(mod_name + "."))
             and not v.name.startswith("_")
         }
-        if module_classes:
-            lines.append("| Class | Methods | Description | Source |")
-            lines.append("|-------|---------|-------------|--------|")
-            for cls_name, cls_info in sorted(module_classes.items()):
-                doc = cls_info.docstring.splitlines()[0] if cls_info.docstring else "—"
-                public_methods = [m for m in cls_info.methods
-                                  if not m.split(".")[-1].startswith("_")]
-                src = self._linker.source_link(cls_info.file, cls_info.line)
-                lines.append(f"| `{cls_info.name}` | {len(public_methods)} | {doc} | {src} |")
-            lines.append("")
-
-            # Expand methods for important classes (>2 public methods)
-            for cls_name, cls_info in sorted(module_classes.items()):
-                methods = self._get_public_methods(cls_info)
-                if len(methods) >= 2:
-                    lines.append(f"**`{cls_info.name}` methods:**\n")
-                    for m in methods:
-                        sig = self._format_signature(m)
-                        doc = f" — {m.docstring.splitlines()[0]}" if m.docstring else ""
-                        lines.append(f"- `{sig}`{doc}")
-                    lines.append("")
-
-        # Functions table
-        module_functions = {
+
+    def _get_module_functions(self, mod_name: str) -> Dict[str, FunctionInfo]:
+        """Get all public functions for a module."""
+        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 and not v.name.startswith("_")
         }
-        if module_functions:
-            lines.append("| Function | Signature | CC | Description | Source |")
-            lines.append("|----------|-----------|----|-----------  |--------|")
-            for func_name, func_info in sorted(module_functions.items()):
-                sig = self._format_signature(func_info)
-                cc = func_info.complexity.get(
-                    "cyclomatic_complexity",
-                    func_info.complexity.get("cyclomatic", "—"),
-                )
-                doc = func_info.docstring.splitlines()[0] if func_info.docstring else "—"
-                warn = " ⚠️" if isinstance(cc, (int, float)) and cc > 10 else ""
-                src = self._linker.source_link(func_info.file, func_info.line)
-                lines.append(f"| `{func_info.name}` | `{sig}` | {cc}{warn} | {doc} | {src} |")
-            lines.append("")
 
-        return "\n".join(lines)
+    def _render_classes_table(self, module_classes: Dict[str, ClassInfo]) -> List[str]:
+        """Render the classes summary table."""
+        lines = ["| Class | Methods | Description | Source |", "|-------|---------|-------------|--------|"]
+        for cls_name, cls_info in sorted(module_classes.items()):
+            doc = cls_info.docstring.splitlines()[0] if cls_info.docstring else "—"
+            public_methods = [m for m in cls_info.methods
+                              if not m.split(".")[-1].startswith("_")]
+            src = self._linker.source_link(cls_info.file, cls_info.line)
+            lines.append(f"| `{cls_info.name}` | {len(public_methods)} | {doc} | {src} |")
+        lines.append("")
+        return lines
+
+    def _render_class_methods(self, module_classes: Dict[str, ClassInfo]) -> List[str]:
+        """Render expanded methods for classes with >=2 public methods."""
+        lines = []
+        for cls_name, cls_info in sorted(module_classes.items()):
+            methods = self._get_public_methods(cls_info)
+            if len(methods) >= 2:
+                lines.append(f"**`{cls_info.name}` methods:**\n")
+                for m in methods:
+                    sig = self._format_signature(m)
+                    doc = f" — {m.docstring.splitlines()[0]}" if m.docstring else ""
+                    lines.append(f"- `{sig}`{doc}")
+                lines.append("")
+        return lines
+
+    def _render_functions_table(self, module_functions: Dict[str, FunctionInfo]) -> List[str]:
+        """Render the functions summary table."""
+        lines = ["| Function | Signature | CC | Description | Source |", "|----------|-----------|----|-----------  |--------|"]
+        for func_name, func_info in sorted(module_functions.items()):
+            sig = self._format_signature(func_info)
+            cc = func_info.complexity.get(
+                "cyclomatic_complexity",
+                func_info.complexity.get("cyclomatic", "—"),
+            )
+            doc = func_info.docstring.splitlines()[0] if func_info.docstring else "—"
+            warn = " ⚠️" if isinstance(cc, (int, float)) and cc > 10 else ""
+            src = self._linker.source_link(func_info.file, func_info.line)
+            lines.append(f"| `{func_info.name}` | `{sig}` | {cc}{warn} | {doc} | {src} |")
+        lines.append("")
+        return lines
 
     def _get_public_methods(self, cls_info: ClassInfo) -> List[FunctionInfo]:
         """Get public (non-dunder) methods of a class."""

code2docs/generators/code2llm_gen.py

@@ -11,54 +11,79 @@ from ..config import Code2DocsConfig
 
 def parse_gitignore(project_path: Path) -> List[str]:
     """Parse .gitignore file and return list of patterns to exclude.
-    
+
     Filters out:
     - Empty lines
     - Comments (lines starting with #)
     - Negation patterns (starting with !)
     - Complex patterns with ** or regex
-    
+
     Returns simple directory/file patterns that can be passed to --skip-subprojects.
     """
     gitignore_path = project_path / ".gitignore"
     if not gitignore_path.exists():
         return []
-    
-    patterns = []
+
     try:
         content = gitignore_path.read_text(encoding="utf-8")
-        for line in content.split("\n"):
-            line = line.strip()
-            # Skip empty lines and comments
-            if not line or line.startswith("#"):
-                continue
-            # Skip negation patterns (too complex)
-            if line.startswith("!"):
-                continue
-            # Skip patterns with ** (globstar - too complex)
-            if "**" in line:
-                continue
-            # Skip file-specific patterns (with wildcards)
-            if "*" in line and "/" not in line:
-                # Wildcard without path - likely file pattern, skip
-                continue
-            # Clean up the pattern
-            pattern = line.rstrip("/")  # Remove trailing slash
-            # Skip patterns starting with / (root-only patterns)
-            if pattern.startswith("/"):
-                pattern = pattern[1:]
-            # Skip if still has special characters
-            if any(c in pattern for c in "[]?*"):
-                continue
-            # Valid directory pattern
-            if pattern and len(pattern) > 1:
-                patterns.append(pattern)
+        return _extract_patterns(content)
     except Exception:
-        pass  # Silently fail if can't read gitignore
-    
+        return []
+
+
+def _extract_patterns(content: str) -> List[str]:
+    """Extract valid patterns from gitignore content."""
+    patterns = []
+    for line in content.split("\n"):
+        pattern = _process_line(line)
+        if pattern:
+            patterns.append(pattern)
     return patterns
 
 
+def _process_line(line: str) -> str:
+    """Process a single gitignore line, returning valid pattern or empty string."""
+    line = line.strip()
+
+    if _should_skip_line(line):
+        return ""
+
+    pattern = _clean_pattern(line)
+    if _is_valid_pattern(pattern):
+        return pattern
+    return ""
+
+
+def _should_skip_line(line: str) -> bool:
+    """Check if line should be skipped (empty, comment, negation, globstar)."""
+    if not line or line.startswith("#"):
+        return True
+    if line.startswith("!"):
+        return True
+    if "**" in line:
+        return True
+    if "*" in line and "/" not in line:
+        return True
+    return False
+
+
+def _clean_pattern(line: str) -> str:
+    """Clean up the pattern by removing trailing slashes and leading slashes."""
+    pattern = line.rstrip("/")
+    if pattern.startswith("/"):
+        pattern = pattern[1:]
+    return pattern
+
+
+def _is_valid_pattern(pattern: str) -> bool:
+    """Check if pattern is valid (no special chars, length > 1)."""
+    if not pattern or len(pattern) <= 1:
+        return False
+    if any(c in pattern for c in "[]?*"):
+        return False
+    return True
+
+
 class Code2LlmGenerator:
     """Generate code2llm analysis files in project/ directory.
     
@@ -124,8 +149,15 @@ class Code2LlmGenerator:
     def _run_code2llm(self, project_path: Path, output_dir: Path) -> None:
         """Execute code2llm CLI with appropriate options."""
         cfg = self.config.code2llm
-        
-        cmd = [
+
+        cmd = self._build_base_cmd(project_path, output_dir, cfg)
+        self._add_config_options(cmd, cfg)
+        self._add_exclude_patterns(cmd, cfg, project_path)
+        self._execute_command(cmd, project_path)
+
+    def _build_base_cmd(self, project_path: Path, output_dir: Path, cfg) -> List[str]:
+        """Build base command with required options."""
+        return [
             "python", "-m", "code2llm",
             str(project_path),
             "-f", ",".join(cfg.formats),
@@ -133,41 +165,51 @@ class Code2LlmGenerator:
             "--strategy", cfg.strategy,
             "--max-depth", str(cfg.max_depth),
         ]
-        
-        # Add options based on config
+
+    def _add_config_options(self, cmd: List[str], cfg) -> None:
+        """Add optional flags based on config settings."""
         if not cfg.chunk:
             cmd.append("--no-chunk")
         if cfg.no_png:
             cmd.append("--no-png")
         if self.config.verbose:
             cmd.append("-v")
-        
-        # Add exclude patterns as skip-subprojects if specified
-        if cfg.exclude_patterns:
-            # Convert patterns to skip-subprojects (folders to skip)
-            skip_dirs = [p for p in cfg.exclude_patterns if not p.startswith(".") and not p.startswith("*")]
-            if skip_dirs:
-                cmd.extend(["--skip-subprojects"] + skip_dirs[:10])  # Limit to 10
-        
-        # Add patterns from .gitignore
+
+    def _add_exclude_patterns(self, cmd: List[str], cfg, project_path: Path) -> None:
+        """Add exclude patterns from config and .gitignore."""
+        skip_dirs = self._get_config_skip_dirs(cfg)
         gitignore_patterns = parse_gitignore(project_path)
-        if gitignore_patterns:
-            # Merge with existing patterns, remove duplicates
-            existing = set(skip_dirs) if cfg.exclude_patterns else set()
-            new_patterns = [p for p in gitignore_patterns if p not in existing][:10]
-            if new_patterns:
-                if "--skip-subprojects" not in cmd:
-                    cmd.append("--skip-subprojects")
-                cmd.extend(new_patterns)
-        
-        # Run the command
+
+        all_patterns = self._merge_patterns(skip_dirs, gitignore_patterns)
+        if all_patterns:
+            cmd.append("--skip-subprojects")
+            cmd.extend(all_patterns[:10])
+
+    def _get_config_skip_dirs(self, cfg) -> List[str]:
+        """Get skip directories from config exclude patterns."""
+        if not cfg.exclude_patterns:
+            return []
+        return [p for p in cfg.exclude_patterns if not p.startswith(".") and not p.startswith("*")]
+
+    def _merge_patterns(self, config_patterns: List[str], gitignore_patterns: List[str]) -> List[str]:
+        """Merge config and gitignore patterns, removing duplicates."""
+        existing = set(config_patterns)
+        merged = list(config_patterns)
+        for p in gitignore_patterns:
+            if p not in existing:
+                merged.append(p)
+                existing.add(p)
+        return merged
+
+    def _execute_command(self, cmd: List[str], project_path: Path) -> None:
+        """Run the subprocess command and handle errors."""
         result = subprocess.run(
             cmd,
             capture_output=True,
             text=True,
             cwd=str(project_path),
         )
-        
+
         # Don't raise on mmdc/png errors (optional dependencies)
         if result.returncode != 0 and "mmdc" not in result.stderr:
             raise RuntimeError(f"code2llm failed: {result.stderr}")

code2docs/generators/contributing_gen.py

@@ -186,36 +186,51 @@ class ContributingGenerator:
         """Render code style guidelines."""
         lang = tools.get("language", "python")
         lines = ["## Code Style\n"]
+        lines.extend(ContributingGenerator._get_style_lines(lang, tools))
+        return "\n".join(lines)
 
+    @staticmethod
+    def _get_style_lines(lang: str, tools: Dict[str, bool]) -> list:
+        """Get style guideline lines for the language."""
         if lang in ("javascript", "typescript"):
-            if tools.get("eslint"):
-                lines.append("- **Linting:** [ESLint](https://eslint.org/) — `npx eslint .`")
-            if tools.get("prettier"):
-                lines.append("- **Formatting:** [Prettier](https://prettier.io/) — `npx prettier --write .`")
-            if tools.get("typescript"):
-                lines.append("- **Type checking:** TypeScript — `npx tsc --noEmit`")
-            if not any(tools.get(t) for t in ("eslint", "prettier")):
-                lines.append("Follow the project's ESLint/Prettier configuration.")
-        elif lang == "rust":
-            lines.append("- **Formatting:** `cargo fmt`")
-            lines.append("- **Linting:** `cargo clippy`")
-        elif lang == "go":
-            lines.append("- **Formatting:** `gofmt -w .`")
-            lines.append("- **Linting:** `go vet ./...`")
-        else:
-            if tools.get("black"):
-                lines.append("- **Formatting:** [Black](https://black.readthedocs.io/) — `black .`")
-            if tools.get("ruff"):
-                lines.append("- **Linting:** [Ruff](https://docs.astral.sh/ruff/) — `ruff check .`")
-            if tools.get("mypy"):
-                lines.append("- **Type checking:** [mypy](https://mypy.readthedocs.io/) — `mypy .`")
-            if tools.get("flake8"):
-                lines.append("- **Linting:** [flake8](https://flake8.pycqa.org/) — `flake8 .`")
-            if tools.get("isort"):
-                lines.append("- **Imports:** [isort](https://pycqa.github.io/isort/) — `isort .`")
-            if not any(tools.get(t) for t in ("black", "ruff", "mypy", "flake8", "isort")):
-                lines.append("Follow PEP 8 conventions.")
-        return "\n".join(lines)
+            return ContributingGenerator._get_jsts_style_lines(tools)
+        if lang == "rust":
+            return ["- **Formatting:** `cargo fmt`", "- **Linting:** `cargo clippy`"]
+        if lang == "go":
+            return ["- **Formatting:** `gofmt -w .`", "- **Linting:** `go vet ./...`"]
+        return ContributingGenerator._get_python_style_lines(tools)
+
+    @staticmethod
+    def _get_jsts_style_lines(tools: Dict[str, bool]) -> list:
+        """Get JavaScript/TypeScript style lines."""
+        lines = []
+        if tools.get("eslint"):
+            lines.append("- **Linting:** [ESLint](https://eslint.org/) — `npx eslint .`")
+        if tools.get("prettier"):
+            lines.append("- **Formatting:** [Prettier](https://prettier.io/) — `npx prettier --write .`")
+        if tools.get("typescript"):
+            lines.append("- **Type checking:** TypeScript — `npx tsc --noEmit`")
+        if not lines:
+            lines.append("Follow the project's ESLint/Prettier configuration.")
+        return lines
+
+    @staticmethod
+    def _get_python_style_lines(tools: Dict[str, bool]) -> list:
+        """Get Python style lines."""
+        lines = []
+        if tools.get("black"):
+            lines.append("- **Formatting:** [Black](https://black.readthedocs.io/) — `black .`")
+        if tools.get("ruff"):
+            lines.append("- **Linting:** [Ruff](https://docs.astral.sh/ruff/) — `ruff check .`")
+        if tools.get("mypy"):
+            lines.append("- **Type checking:** [mypy](https://mypy.readthedocs.io/) — `mypy .`")
+        if tools.get("flake8"):
+            lines.append("- **Linting:** [flake8](https://flake8.pycqa.org/) — `flake8 .`")
+        if tools.get("isort"):
+            lines.append("- **Imports:** [isort](https://pycqa.github.io/isort/) — `isort .`")
+        if not lines:
+            lines.append("Follow PEP 8 conventions.")
+        return lines
 
     @staticmethod
     def _render_pull_request() -> str: