code2docs 0.1.1__py3-none-any.whl

code2docs/cli.py

@@ -0,0 +1,226 @@
+"""CLI interface for code2docs."""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .config import Code2DocsConfig
+
+
+@click.group(invoke_without_command=True)
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
+@click.option("--readme-only", is_flag=True, help="Generate only README.md")
+@click.option("--sections", "-s", default=None, help="Comma-separated sections to generate")
+@click.option("--output", "-o", default=None, help="Output directory for docs")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--dry-run", is_flag=True, help="Show what would be generated without writing")
+@click.pass_context
+def main(ctx, project_path, config_path, readme_only, sections, output, verbose, dry_run):
+    """code2docs — Auto-generate project documentation from source code.
+
+    Analyzes PROJECT_PATH using code2llm and generates human-readable documentation.
+    """
+    if ctx.invoked_subcommand is not None:
+        ctx.ensure_object(dict)
+        ctx.obj["project_path"] = project_path
+        ctx.obj["config_path"] = config_path
+        ctx.obj["verbose"] = verbose
+        ctx.obj["dry_run"] = dry_run
+        return
+
+    # Default action: full generation
+    config = _load_config(project_path, config_path)
+    if verbose:
+        config.verbose = True
+    if output:
+        config.output = output
+    if sections:
+        config.readme.sections = [s.strip() for s in sections.split(",")]
+
+    _run_generate(project_path, config, readme_only=readme_only, dry_run=dry_run)
+
+
+@main.command()
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--dry-run", is_flag=True, help="Show what would change without writing")
+def sync(project_path, config_path, verbose, dry_run):
+    """Synchronize documentation with source code changes."""
+    config = _load_config(project_path, config_path)
+    if verbose:
+        config.verbose = True
+
+    _run_sync(project_path, config, dry_run=dry_run)
+
+
+@main.command()
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+def watch(project_path, config_path, verbose):
+    """Watch for file changes and auto-regenerate docs."""
+    config = _load_config(project_path, config_path)
+    if verbose:
+        config.verbose = True
+
+    _run_watch(project_path, config)
+
+
+@main.command()
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--output", "-o", default="code2docs.yaml", help="Output config file path")
+def init(project_path, output):
+    """Initialize code2docs.yaml configuration file."""
+    project_path = Path(project_path).resolve()
+    config = Code2DocsConfig(
+        project_name=project_path.name,
+        source="./",
+    )
+    out_path = project_path / output
+    config.to_yaml(str(out_path))
+    click.echo(f"Created {out_path}")
+
+
+def _load_config(project_path: str, config_path: Optional[str] = None) -> Code2DocsConfig:
+    """Load configuration, auto-detecting code2docs.yaml if present."""
+    project = Path(project_path).resolve()
+
+    if config_path:
+        return Code2DocsConfig.from_yaml(config_path)
+
+    # Auto-detect
+    for name in ("code2docs.yaml", "code2docs.yml"):
+        candidate = project / name
+        if candidate.exists():
+            return Code2DocsConfig.from_yaml(str(candidate))
+
+    # Defaults
+    config = Code2DocsConfig(project_name=project.name, source="./")
+    return config
+
+
+def _run_generate(project_path: str, config: Code2DocsConfig,
+                  readme_only: bool = False, dry_run: bool = False):
+    """Run full documentation generation."""
+    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
+    from .generators.examples_gen import ExamplesGenerator
+    from .generators.architecture_gen import ArchitectureGenerator
+
+    project = Path(project_path).resolve()
+    click.echo(f"📖 code2docs: analyzing {project.name}...")
+
+    # Step 1: Analyze
+    scanner = ProjectScanner(config)
+    result = scanner.analyze(str(project))
+
+    if config.verbose:
+        click.echo(f"  Functions: {len(result.functions)}")
+        click.echo(f"  Classes: {len(result.classes)}")
+        click.echo(f"  Modules: {len(result.modules)}")
+
+    # Step 2: Generate README
+    readme_gen = ReadmeGenerator(config, result)
+    readme_content = readme_gen.generate()
+
+    if dry_run:
+        click.echo(f"\n--- README.md ({len(readme_content)} chars) ---")
+        click.echo(readme_content[:500] + "..." if len(readme_content) > 500 else readme_content)
+    else:
+        readme_path = project / config.readme_output
+        readme_gen.write(str(readme_path), readme_content)
+        click.echo(f"  ✅ {readme_path.relative_to(project)}")
+
+    if readme_only:
+        return
+
+    # Step 3: Generate docs/
+    docs_dir = project / config.output
+    docs_dir.mkdir(parents=True, exist_ok=True)
+
+    if config.docs.api_reference:
+        api_gen = ApiReferenceGenerator(config, result)
+        files = api_gen.generate_all()
+        if not dry_run:
+            api_gen.write_all(str(docs_dir / "api"), files)
+            click.echo(f"  ✅ docs/api/ ({len(files)} files)")
+        else:
+            click.echo(f"  [dry-run] docs/api/ ({len(files)} files)")
+
+    if config.docs.module_docs:
+        mod_gen = ModuleDocsGenerator(config, result)
+        files = mod_gen.generate_all()
+        if not dry_run:
+            mod_gen.write_all(str(docs_dir / "modules"), files)
+            click.echo(f"  ✅ docs/modules/ ({len(files)} files)")
+        else:
+            click.echo(f"  [dry-run] docs/modules/ ({len(files)} files)")
+
+    if config.docs.architecture:
+        arch_gen = ArchitectureGenerator(config, result)
+        content = arch_gen.generate()
+        if not dry_run:
+            arch_path = docs_dir / "architecture.md"
+            arch_path.write_text(content, encoding="utf-8")
+            click.echo(f"  ✅ docs/architecture.md")
+        else:
+            click.echo(f"  [dry-run] docs/architecture.md")
+
+    # Step 4: Generate examples/
+    if config.examples.auto_generate:
+        ex_gen = ExamplesGenerator(config, result)
+        files = ex_gen.generate_all()
+        if not dry_run:
+            examples_dir = project / "examples"
+            ex_gen.write_all(str(examples_dir), files)
+            click.echo(f"  ✅ examples/ ({len(files)} files)")
+        else:
+            click.echo(f"  [dry-run] examples/ ({len(files)} files)")
+
+    click.echo("📖 Done!")
+
+
+def _run_sync(project_path: str, config: Code2DocsConfig, dry_run: bool = False):
+    """Run sync — regenerate only changed documentation."""
+    from .sync.differ import Differ
+    from .sync.updater import Updater
+
+    project = Path(project_path).resolve()
+    click.echo(f"🔄 code2docs sync: {project.name}...")
+
+    differ = Differ(config)
+    changes = differ.detect_changes(str(project))
+
+    if not changes:
+        click.echo("  No changes detected.")
+        return
+
+    click.echo(f"  Changes detected in {len(changes)} modules")
+
+    if dry_run:
+        for change in changes:
+            click.echo(f"    - {change}")
+        return
+
+    updater = Updater(config)
+    updater.apply(str(project), changes)
+    click.echo("🔄 Sync complete!")
+
+
+def _run_watch(project_path: str, config: Code2DocsConfig):
+    """Run file watcher for auto-resync."""
+    try:
+        from .sync.watcher import start_watcher
+    except ImportError:
+        click.echo("Error: watchdog not installed. Install with: pip install code2docs[watch]")
+        sys.exit(1)
+
+    project = Path(project_path).resolve()
+    click.echo(f"👁 Watching {project.name} for changes... (Ctrl+C to stop)")
+    start_watcher(str(project), config)

code2docs/config.py

@@ -0,0 +1,158 @@
+"""Configuration for code2docs documentation generation."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+
+@dataclass
+class ReadmeConfig:
+    """Configuration for README generation."""
+    sections: List[str] = field(default_factory=lambda: [
+        "overview", "install", "quickstart", "api", "structure", "endpoints",
+    ])
+    badges: List[str] = field(default_factory=lambda: [
+        "version", "python", "coverage", "complexity",
+    ])
+    sync_markers: bool = True
+
+
+@dataclass
+class DocsConfig:
+    """Configuration for docs/ generation."""
+    api_reference: bool = True
+    module_docs: bool = True
+    architecture: bool = True
+    changelog: bool = True
+
+
+@dataclass
+class ExamplesConfig:
+    """Configuration for examples/ generation."""
+    auto_generate: bool = True
+    from_entry_points: bool = True
+
+
+@dataclass
+class SyncConfig:
+    """Configuration for synchronization."""
+    strategy: str = "markers"  # markers | full | git-diff
+    watch: bool = False
+    ignore: List[str] = field(default_factory=lambda: ["tests/", "__pycache__"])
+
+
+@dataclass
+class Code2DocsConfig:
+    """Main configuration for code2docs."""
+    project_name: str = ""
+    source: str = "./"
+    output: str = "./docs/"
+    readme_output: str = "./README.md"
+
+    readme: ReadmeConfig = field(default_factory=ReadmeConfig)
+    docs: DocsConfig = field(default_factory=DocsConfig)
+    examples: ExamplesConfig = field(default_factory=ExamplesConfig)
+    sync: SyncConfig = field(default_factory=SyncConfig)
+
+    # code2llm analysis options
+    verbose: bool = False
+    exclude_tests: bool = True
+    skip_private: bool = False
+
+    @classmethod
+    def from_yaml(cls, path: str) -> "Code2DocsConfig":
+        """Load configuration from code2docs.yaml."""
+        config_path = Path(path)
+        if not config_path.exists():
+            return cls()
+
+        with open(config_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+
+        config = cls()
+
+        # Project-level settings
+        project = data.get("project", {})
+        config.project_name = project.get("name", "")
+        config.source = project.get("source", "./")
+        config.output = project.get("output", "./docs/")
+        config.readme_output = project.get("readme_output", "./README.md")
+        config.verbose = project.get("verbose", False)
+        config.exclude_tests = project.get("exclude_tests", True)
+        config.skip_private = project.get("skip_private", False)
+
+        # Readme config
+        readme_data = data.get("readme", {})
+        if readme_data:
+            config.readme = ReadmeConfig(
+                sections=readme_data.get("sections", config.readme.sections),
+                badges=readme_data.get("badges", config.readme.badges),
+                sync_markers=readme_data.get("sync_markers", True),
+            )
+
+        # Docs config
+        docs_data = data.get("docs", {})
+        if docs_data:
+            config.docs = DocsConfig(
+                api_reference=docs_data.get("api_reference", True),
+                module_docs=docs_data.get("module_docs", True),
+                architecture=docs_data.get("architecture", True),
+                changelog=docs_data.get("changelog", True),
+            )
+
+        # Examples config
+        examples_data = data.get("examples", {})
+        if examples_data:
+            config.examples = ExamplesConfig(
+                auto_generate=examples_data.get("auto_generate", True),
+                from_entry_points=examples_data.get("from_entry_points", True),
+            )
+
+        # Sync config
+        sync_data = data.get("sync", {})
+        if sync_data:
+            config.sync = SyncConfig(
+                strategy=sync_data.get("strategy", "markers"),
+                watch=sync_data.get("watch", False),
+                ignore=sync_data.get("ignore", ["tests/", "__pycache__"]),
+            )
+
+        return config
+
+    def to_yaml(self, path: str) -> None:
+        """Save configuration to YAML file."""
+        data = {
+            "project": {
+                "name": self.project_name,
+                "source": self.source,
+                "output": self.output,
+                "readme_output": self.readme_output,
+                "verbose": self.verbose,
+                "exclude_tests": self.exclude_tests,
+                "skip_private": self.skip_private,
+            },
+            "readme": {
+                "sections": self.readme.sections,
+                "badges": self.readme.badges,
+                "sync_markers": self.readme.sync_markers,
+            },
+            "docs": {
+                "api_reference": self.docs.api_reference,
+                "module_docs": self.docs.module_docs,
+                "architecture": self.docs.architecture,
+                "changelog": self.docs.changelog,
+            },
+            "examples": {
+                "auto_generate": self.examples.auto_generate,
+                "from_entry_points": self.examples.from_entry_points,
+            },
+            "sync": {
+                "strategy": self.sync.strategy,
+                "watch": self.sync.watch,
+                "ignore": self.sync.ignore,
+            },
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)

code2docs/formatters/__init__.py

@@ -0,0 +1,7 @@
+"""Formatters — Markdown rendering, badges, TOC generation."""
+
+from .markdown import MarkdownFormatter
+from .badges import generate_badges
+from .toc import generate_toc
+
+__all__ = ["MarkdownFormatter", "generate_badges", "generate_toc"]

code2docs/formatters/badges.py

@@ -0,0 +1,52 @@
+"""Badge generation using shields.io URLs."""
+
+from typing import Dict, List, Optional
+from urllib.parse import quote
+
+
+def generate_badges(project_name: str, badge_types: List[str],
+                    stats: Dict = None, deps=None) -> str:
+    """Generate shields.io badge Markdown strings."""
+    stats = stats or {}
+    badges: List[str] = []
+
+    for badge_type in badge_types:
+        badge = _make_badge(badge_type, project_name, stats, deps)
+        if badge:
+            badges.append(badge)
+
+    return " ".join(badges)
+
+
+def _make_badge(badge_type: str, project_name: str,
+                stats: Dict, deps) -> Optional[str]:
+    """Create a single badge Markdown string."""
+    name = quote(project_name)
+
+    if badge_type == "version":
+        return f"![version](https://img.shields.io/badge/version-0.1.0-blue)"
+
+    elif badge_type == "python":
+        py_version = ""
+        if deps and hasattr(deps, "python_version"):
+            py_version = deps.python_version
+        py_version = py_version or ">=3.9"
+        py_safe = quote(py_version)
+        return f"![python](https://img.shields.io/badge/python-{py_safe}-blue)"
+
+    elif badge_type == "coverage":
+        return f"![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey)"
+
+    elif badge_type == "complexity":
+        funcs = stats.get("functions_found", 0)
+        if funcs:
+            return f"![functions](https://img.shields.io/badge/functions-{funcs}-green)"
+        return None
+
+    elif badge_type == "license":
+        return f"![license](https://img.shields.io/badge/license-Apache%202.0-green)"
+
+    elif badge_type == "docs":
+        return f"![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)"
+
+    return None

code2docs/formatters/markdown.py

@@ -0,0 +1,73 @@
+"""Markdown formatting utilities."""
+
+from typing import Dict, List, Optional
+
+
+class MarkdownFormatter:
+    """Helper for constructing Markdown documents."""
+
+    def __init__(self):
+        self.lines: List[str] = []
+
+    def heading(self, text: str, level: int = 1) -> "MarkdownFormatter":
+        """Add a heading."""
+        self.lines.append(f"{'#' * level} {text}\n")
+        return self
+
+    def paragraph(self, text: str) -> "MarkdownFormatter":
+        """Add a paragraph."""
+        self.lines.append(f"{text}\n")
+        return self
+
+    def blockquote(self, text: str) -> "MarkdownFormatter":
+        """Add a blockquote."""
+        self.lines.append(f"> {text}\n")
+        return self
+
+    def code_block(self, code: str, language: str = "") -> "MarkdownFormatter":
+        """Add a fenced code block."""
+        self.lines.append(f"```{language}")
+        self.lines.append(code)
+        self.lines.append("```\n")
+        return self
+
+    def inline_code(self, text: str) -> str:
+        """Return inline code string."""
+        return f"`{text}`"
+
+    def bold(self, text: str) -> str:
+        """Return bold string."""
+        return f"**{text}**"
+
+    def link(self, text: str, url: str) -> str:
+        """Return a Markdown link."""
+        return f"[{text}]({url})"
+
+    def list_item(self, text: str, indent: int = 0) -> "MarkdownFormatter":
+        """Add a list item."""
+        prefix = "  " * indent
+        self.lines.append(f"{prefix}- {text}")
+        return self
+
+    def table(self, headers: List[str], rows: List[List[str]]) -> "MarkdownFormatter":
+        """Add a Markdown table."""
+        self.lines.append("| " + " | ".join(headers) + " |")
+        self.lines.append("| " + " | ".join("---" for _ in headers) + " |")
+        for row in rows:
+            self.lines.append("| " + " | ".join(str(c) for c in row) + " |")
+        self.lines.append("")
+        return self
+
+    def separator(self) -> "MarkdownFormatter":
+        """Add a horizontal rule."""
+        self.lines.append("---\n")
+        return self
+
+    def blank(self) -> "MarkdownFormatter":
+        """Add a blank line."""
+        self.lines.append("")
+        return self
+
+    def render(self) -> str:
+        """Render accumulated Markdown to string."""
+        return "\n".join(self.lines)

code2docs/formatters/toc.py

@@ -0,0 +1,63 @@
+"""Table of contents generator from Markdown headings."""
+
+import re
+from typing import List, Tuple
+
+
+def generate_toc(markdown_content: str, max_depth: int = 3) -> str:
+    """Generate a table of contents from Markdown headings.
+
+    Args:
+        markdown_content: Full Markdown document.
+        max_depth: Maximum heading level to include (1-6).
+
+    Returns:
+        TOC as Markdown string.
+    """
+    headings = extract_headings(markdown_content, max_depth)
+    if not headings:
+        return ""
+
+    lines = ["## Table of Contents\n"]
+    for level, text, anchor in headings:
+        indent = "  " * (level - 1)
+        lines.append(f"{indent}- [{text}](#{anchor})")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def extract_headings(content: str, max_depth: int = 3) -> List[Tuple[int, str, str]]:
+    """Extract headings from Markdown content.
+
+    Returns list of (level, text, anchor) tuples.
+    """
+    headings: List[Tuple[int, str, str]] = []
+    in_code_block = False
+
+    for line in content.splitlines():
+        # Skip code blocks
+        if line.strip().startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+
+        match = re.match(r'^(#{1,6})\s+(.+)$', line)
+        if match:
+            level = len(match.group(1))
+            if level <= max_depth:
+                text = match.group(2).strip()
+                anchor = _slugify(text)
+                headings.append((level, text, anchor))
+
+    return headings
+
+
+def _slugify(text: str) -> str:
+    """Convert heading text to GitHub-compatible anchor slug."""
+    slug = text.lower()
+    slug = re.sub(r'[^\w\s-]', '', slug)
+    slug = re.sub(r'[\s]+', '-', slug)
+    slug = slug.strip('-')
+    return slug

code2docs/generators/__init__.py

@@ -0,0 +1,42 @@
+"""Documentation generators — produce Markdown, examples, and diagrams."""
+
+from .readme_gen import ReadmeGenerator
+from .api_reference_gen import ApiReferenceGenerator
+from .module_docs_gen import ModuleDocsGenerator
+from .examples_gen import ExamplesGenerator
+from .architecture_gen import ArchitectureGenerator
+from .changelog_gen import ChangelogGenerator
+
+__all__ = [
+    "ReadmeGenerator",
+    "ApiReferenceGenerator",
+    "ModuleDocsGenerator",
+    "ExamplesGenerator",
+    "ArchitectureGenerator",
+    "ChangelogGenerator",
+    "generate_docs",
+]
+
+
+def generate_docs(project_path: str, config=None):
+    """High-level function to generate all documentation."""
+    from ..analyzers.project_scanner import ProjectScanner
+    from ..config import Code2DocsConfig
+
+    config = config or Code2DocsConfig()
+    scanner = ProjectScanner(config)
+    result = scanner.analyze(project_path)
+
+    docs = {}
+    docs["readme"] = ReadmeGenerator(config, result).generate()
+
+    if config.docs.api_reference:
+        docs["api"] = ApiReferenceGenerator(config, result).generate_all()
+
+    if config.docs.module_docs:
+        docs["modules"] = ModuleDocsGenerator(config, result).generate_all()
+
+    if config.docs.architecture:
+        docs["architecture"] = ArchitectureGenerator(config, result).generate()
+
+    return docs