code2docs 0.1.1__py3-none-any.whl

code2docs/sync/watcher.py

@@ -0,0 +1,75 @@
+"""File watcher for auto-resync on source changes (requires watchdog)."""
+
+import time
+from pathlib import Path
+from typing import Optional
+
+from ..config import Code2DocsConfig
+
+
+def start_watcher(project_path: str, config: Optional[Code2DocsConfig] = None) -> None:
+    """Start watching project for file changes and auto-resync docs.
+
+    Requires watchdog package: pip install code2docs[watch]
+    """
+    try:
+        from watchdog.observers import Observer
+        from watchdog.events import FileSystemEventHandler, FileModifiedEvent
+    except ImportError:
+        raise ImportError(
+            "watchdog is required for watch mode. "
+            "Install with: pip install code2docs[watch]"
+        )
+
+    config = config or Code2DocsConfig()
+    project = Path(project_path).resolve()
+
+    class DocsHandler(FileSystemEventHandler):
+        """Handler that triggers resync on Python file changes."""
+
+        def __init__(self):
+            self._last_trigger = 0.0
+            self._debounce_seconds = 2.0
+
+        def on_modified(self, event):
+            if not event.src_path.endswith(".py"):
+                return
+
+            # Check ignore patterns
+            rel = str(Path(event.src_path).relative_to(project))
+            for pattern in config.sync.ignore:
+                if pattern.rstrip("/") in rel:
+                    return
+
+            # Debounce
+            now = time.time()
+            if now - self._last_trigger < self._debounce_seconds:
+                return
+            self._last_trigger = now
+
+            print(f"  Change detected: {rel}")
+            try:
+                from .differ import Differ
+                from .updater import Updater
+
+                differ = Differ(config)
+                changes = differ.detect_changes(str(project))
+                if changes:
+                    print(f"  Regenerating {len(changes)} changed modules...")
+                    updater = Updater(config)
+                    updater.apply(str(project), changes)
+                    print("  Done.")
+            except Exception as e:
+                print(f"  Error during resync: {e}")
+
+    handler = DocsHandler()
+    observer = Observer()
+    observer.schedule(handler, str(project), recursive=True)
+    observer.start()
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()
+    observer.join()

code2docs/templates/api_module.md.j2

@@ -0,0 +1,62 @@
+# `{{ module_name }}`
+
+> Source: `{{ module_info.file }}`
+
+{% if classes %}
+## Classes
+
+{% for cls_name, cls_info in classes.items() %}
+### `{{ cls_info.name }}`
+
+{% if cls_info.bases %}
+Inherits from: {% for b in cls_info.bases %}`{{ b }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+{% endif %}
+{% if cls_info.docstring %}
+{{ cls_info.docstring }}
+
+{% endif %}
+{% if methods[cls_name] %}
+#### Methods
+
+{% for method in methods[cls_name] %}
+{% set args = method.args|join(', ') %}
+{% set ret = ' → ' ~ method.returns if method.returns else '' %}
+{% set cc = method.complexity.get('cyclomatic', 0) %}
+- `{{ method.name }}({{ args }}){{ ret }}`{% if method.docstring %} — {{ method.docstring.split('\n')[0] }}{% endif %}{% if cc > 10 %} ⚠️ CC={{ cc }}{% endif %}
+
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if functions %}
+## Functions
+
+{% for func_name, func in functions.items() %}
+{% set args = func.args|join(', ') %}
+{% set ret = ' → ' ~ func.returns if func.returns else '' %}
+### `{{ func.name }}({{ args }}){{ ret }}`
+
+{% if func.docstring %}
+{{ func.docstring }}
+
+{% endif %}
+{% set cc = func.complexity.get('cyclomatic', 0) %}
+{% if cc %}
+- Complexity: {{ cc }}
+{% endif %}
+{% if func.calls %}
+- Calls: {% for c in func.calls[:10] %}`{{ c }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if module_info.imports %}
+## Imports
+
+{% for imp in module_info.imports|sort %}
+- `{{ imp }}`
+{% endfor %}
+{% endif %}

code2docs/templates/architecture.md.j2

@@ -0,0 +1,45 @@
+# {{ project_name }} — Architecture
+
+> Auto-generated from {{ module_count }} modules, {{ function_count }} functions, {{ class_count }} classes
+
+## Module Dependency Graph
+
+{{ module_graph }}
+
+{% if layers %}
+## Architecture Layers
+
+{% for layer_name, modules in layers.items() %}
+### {{ layer_name }}
+
+{% for mod in modules %}
+- `{{ mod }}`
+{% endfor %}
+
+{% endfor %}
+{% endif %}
+
+## Key Classes
+
+{{ class_diagram }}
+
+{% if patterns %}
+## Detected Patterns
+
+{% for pattern in patterns %}
+- **{{ pattern.name }}** ({{ pattern.type }}) — confidence: {{ "%.0f%%"|format(pattern.confidence * 100) }}, functions: {% for f in pattern.functions[:5] %}`{{ f }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+{% endfor %}
+{% endif %}
+
+{% if entry_points %}
+## Entry Points
+
+{% for ep in entry_points %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Metrics Summary
+
+{{ metrics_table }}

code2docs/templates/example_usage.py.j2

@@ -0,0 +1,12 @@
+"""{{ title }} — auto-generated by code2docs."""
+{% for imp in imports %}
+{{ imp }}
+{% endfor %}
+
+{% for example in examples %}
+# {{ example.description }}
+{% if example.code %}
+{{ example.code }}
+{% endif %}
+
+{% endfor %}

code2docs/templates/index.md.j2

@@ -0,0 +1,31 @@
+# {{ project_name }} — Documentation
+
+> Auto-generated by [code2docs](https://github.com/wronai/code2docs)
+
+## Contents
+
+- [Architecture](architecture.md)
+{% if api_reference %}
+- [API Reference](api/index.md)
+{% endif %}
+{% if module_docs %}
+- [Module Documentation](modules/)
+{% endif %}
+{% if changelog %}
+- [Changelog](changelog.md)
+{% endif %}
+
+## Overview
+
+| Metric | Value |
+|--------|-------|
+| Modules | {{ module_count }} |
+| Functions | {{ function_count }} |
+| Classes | {{ class_count }} |
+{% if avg_complexity %}
+| Avg Complexity | {{ avg_complexity }} |
+{% endif %}
+
+---
+
+*Generated on {{ generated_date }} by code2docs v{{ version }}*

code2docs/templates/readme.md.j2

@@ -0,0 +1,85 @@
+{% if sync_markers %}<!-- code2docs:start -->{% endif %}
+# {{ project_name }}
+
+{% if badges %}{{ badges }}{% endif %}
+
+{% if "overview" in sections %}
+> **{{ stats.get('functions_found', 0) }}** functions | **{{ stats.get('classes_found', 0) }}** classes | **{{ stats.get('files_processed', 0) }}** files | CC̄ = {{ avg_complexity }}
+
+{% endif %}
+{% if "install" in sections and dependencies and dependencies.install_command %}
+## Installation
+
+```bash
+{{ dependencies.install_command }}
+```
+{% if dependencies.python_version %}
+Requires Python {{ dependencies.python_version }}
+{% endif %}
+
+{% if dependencies.dependencies %}
+### Dependencies
+
+{% for dep in dependencies.dependencies %}
+- `{{ dep.name }}` {{ dep.version_spec }}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if "quickstart" in sections %}
+## Quick Start
+
+{% if entry_points %}
+```python
+{% for ep in entry_points[:3] %}
+# Entry point: {{ ep }}
+{% endfor %}
+```
+{% else %}
+```python
+import {{ project_name }}
+```
+{% endif %}
+{% endif %}
+
+{% if "api" in sections %}
+## API Overview
+
+{% if public_classes %}
+### Classes
+
+{% for name, cls in public_classes.items()|list %}
+- **`{{ cls.name }}`**{% if cls.docstring %} — {{ cls.docstring.split('\n')[0] }}{% endif %}
+
+{% endfor %}
+{% endif %}
+
+{% if public_functions %}
+### Functions
+
+{% for name, func in public_functions.items()|list %}
+{% set args = func.args|join(', ') %}
+{% set ret = ' → ' ~ func.returns if func.returns else '' %}
+- `{{ func.name }}({{ args }}){{ ret }}`{% if func.docstring %} — {{ func.docstring.split('\n')[0] }}{% endif %}
+
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if "structure" in sections and module_tree %}
+## Project Structure
+
+{{ module_tree }}
+{% endif %}
+
+{% if "endpoints" in sections and endpoints %}
+## Endpoints
+
+| Method | Path | Function | Framework |
+|--------|------|----------|-----------|
+{% for ep in endpoints %}
+| {{ ep.method }} | `{{ ep.path }}` | `{{ ep.function_name }}` | {{ ep.framework }} |
+{% endfor %}
+{% endif %}
+
+{% if sync_markers %}<!-- code2docs:end -->{% endif %}

code2docs-0.1.1.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: code2docs
+Version: 0.1.1
+Summary: Auto-generate and sync project documentation from source code analysis
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/wronai/code2docs
+Project-URL: Repository, https://github.com/wronai/code2docs
+Project-URL: Issues, https://github.com/wronai/code2docs/issues
+Keywords: documentation,auto-docs,readme-generator,api-reference,code-analysis,static-analysis,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: code2llm>=0.5.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == "watch"
+Provides-Extra: mkdocs
+Requires-Dist: mkdocs>=1.5; extra == "mkdocs"
+Requires-Dist: mkdocs-material>=9.0; extra == "mkdocs"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# code2docs
+
+![version](https://img.shields.io/badge/version-0.1.1-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+
+> Auto-generate and sync project documentation from source code analysis.
+
+**code2docs** uses [code2llm](https://github.com/wronai/code2llm)'s `AnalysisResult` to produce human-readable documentation: README.md, API references, module docs, usage examples, and architecture diagrams.
+
+```
+code2llm  →  AnalysisResult  →  .toon / .mmd / context.md   (for LLM)
+code2docs →  AnalysisResult  →  README.md / docs/ / examples/  (for humans)
+```
+
+## Installation
+
+```bash
+pip install code2docs
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/wronai/code2docs
+cd code2docs
+pip install -e .
+```
+
+### Optional extras
+
+```bash
+pip install code2docs[watch]    # file watcher (watchdog)
+pip install code2docs[mkdocs]   # MkDocs integration
+pip install code2docs[dev]      # development tools
+```
+
+## Quick Start
+
+```bash
+# Generate full documentation for a project
+code2docs ./my-project
+
+# Generate only README
+code2docs ./my-project --readme-only
+
+# Sync (regenerate only changed modules)
+code2docs sync ./my-project
+
+# Watch mode (auto-resync on file changes)
+code2docs watch ./my-project
+
+# Initialize config file
+code2docs init ./my-project
+
+# Dry-run (show what would be generated)
+code2docs ./my-project --dry-run
+```
+
+### Python API
+
+```python
+from code2docs import generate_readme, generate_docs, Code2DocsConfig
+
+# Generate README
+generate_readme("./my-project", output="README.md")
+
+# Generate full docs with custom config
+config = Code2DocsConfig(project_name="mylib", verbose=True)
+docs = generate_docs("./my-project", config=config)
+```
+
+## Generated Output
+
+```
+<project>/
+├── README.md                      # Main README (auto-generated sections)
+├── docs/
+│   ├── index.md                   # Documentation index
+│   ├── architecture.md            # Architecture + Mermaid diagrams
+│   ├── api/
+│   │   ├── index.md               # API overview
+│   │   ├── module_analyzer.md     # Per-module API reference
+│   │   └── ...
+│   └── modules/
+│       ├── analyzer.md            # Detailed module documentation
+│       └── ...
+├── examples/
+│   ├── basic_usage.py             # Auto-generated usage example
+│   ├── class_examples.py          # Class usage examples
+│   └── ...
+└── code2docs.yaml                 # Generator configuration
+```
+
+## Configuration
+
+Create `code2docs.yaml` in your project root (or run `code2docs init`):
+
+```yaml
+project:
+  name: my-project
+  source: ./
+  output: ./docs/
+
+readme:
+  sections:
+    - overview
+    - install
+    - quickstart
+    - api
+    - structure
+    - endpoints
+  badges:
+    - version
+    - python
+    - coverage
+    - complexity
+  sync_markers: true
+
+docs:
+  api_reference: true
+  module_docs: true
+  architecture: true
+  changelog: true
+
+examples:
+  auto_generate: true
+  from_entry_points: true
+
+sync:
+  strategy: markers    # markers | full | git-diff
+  watch: false
+  ignore:
+    - "tests/"
+    - "__pycache__"
+```
+
+## Sync Markers
+
+code2docs can update only specific sections of an existing README using markers:
+
+```markdown
+<!-- code2docs:start -->
+... auto-generated content ...
+<!-- code2docs:end -->
+```
+
+Content outside markers is preserved.
+
+## Architecture
+
+```
+code2docs/
+├── cli.py                    # CLI (click-based)
+├── config.py                 # Configuration (code2docs.yaml)
+├── analyzers/                # Adapters to code2llm + custom detectors
+│   ├── project_scanner.py    # Wrapper on code2llm.ProjectAnalyzer
+│   ├── endpoint_detector.py  # Flask/FastAPI/Django route extraction
+│   ├── docstring_extractor.py
+│   └── dependency_scanner.py
+├── generators/               # Documentation generators
+│   ├── readme_gen.py         # README.md generator
+│   ├── api_reference_gen.py  # docs/api/ reference from signatures
+│   ├── module_docs_gen.py    # docs/modules/ per-module docs
+│   ├── examples_gen.py       # examples/ from signatures
+│   ├── changelog_gen.py      # CHANGELOG from git log
+│   └── architecture_gen.py   # Architecture + Mermaid diagrams
+├── templates/                # Jinja2 templates
+├── sync/                     # Change detection & selective regeneration
+│   ├── differ.py
+│   ├── updater.py
+│   └── watcher.py
+└── formatters/               # Markdown, badges, TOC
+```
+
+## Requirements
+
+- Python >= 3.9
+- [code2llm](https://github.com/wronai/code2llm) >= 0.5.0
+- Jinja2 >= 3.1
+- Click >= 8.0
+- PyYAML >= 6.0
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.
+
+## Author
+
+Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)

code2docs-0.1.1.dist-info/RECORD

@@ -0,0 +1,35 @@
+code2docs/__init__.py,sha256=SVjnL6qDNfeTiIDxrMLSA5nUCxBOHsskx-MRtv2HrFQ,958
+code2docs/__main__.py,sha256=dGGkQIZVFDZXEXa9PWew7cBh7hBAYDWfJ9LeezMf2UI,116
+code2docs/cli.py,sha256=eIqzRk43rJbK2uJ_nVyRh3b7N_q9DR5bhntess3CxKc,8317
+code2docs/config.py,sha256=uDEehtGBtZGW9wOHGADzRF-1leoHCtSfHU_-gKusTcI,5377
+code2docs/analyzers/__init__.py,sha256=lIvbHr8JCuYTd8QJNsR7RANLFdlpIMJEsv-lMO7Avdc,370
+code2docs/analyzers/dependency_scanner.py,sha256=bnPAR9VE1tJNcYTf_4BjF2NG5lv-mswPC_kYgATjljg,5409
+code2docs/analyzers/docstring_extractor.py,sha256=lrjtDh6NLgk-ZTy8BlqbCL0W9pIJP0fIMhfDWuS7G6U,4194
+code2docs/analyzers/endpoint_detector.py,sha256=os7mFpMnLhFL9UaU1aO8hpuRa1oeZspAW97kzj5z1mg,3940
+code2docs/analyzers/project_scanner.py,sha256=igtIvr-DFRNPCmaRjQyODu2uyzdPynM6OAIAVePg3W8,1759
+code2docs/formatters/__init__.py,sha256=3-myGxFceSgOW3g1eQFUJO3tEDF03MbG-7WL1WEylk4,240
+code2docs/formatters/badges.py,sha256=zd3Us9n1-ZVcQTR9GtskHrwaBqBWcKJ_5wL_swNaQT8,1737
+code2docs/formatters/markdown.py,sha256=umUvUyKVuvvT-SysWV6xgEQWpc-_UiR9Trf3hodUyBs,2294
+code2docs/formatters/toc.py,sha256=EBynYUlgkk5W5_QqsRHWbIW2Cfpk3sJulk3FvURHK60,1770
+code2docs/generators/__init__.py,sha256=ijLywzOaI_Rl-Bj8Q-SG2AGQMVR8v4ydrbD89f6Ulzk,1323
+code2docs/generators/api_reference_gen.py,sha256=d-tuf4G2XuYzVl2CPFOW-imGjomhSCjN4HrC4N0RLAk,5982
+code2docs/generators/architecture_gen.py,sha256=O3RaOU4SSNF625EtLzVlYKA_ZSKqPKh6mTPkgg0oP90,7322
+code2docs/generators/changelog_gen.py,sha256=6Vcj02tITC2jhnf53sE841N3vsB7VO9nOKTYq7Oi-cM,4007
+code2docs/generators/examples_gen.py,sha256=6sa11Nab9AnJ7PsGw6CuYXnRRZo0LQrwanGbQQMIKDE,7473
+code2docs/generators/module_docs_gen.py,sha256=Vou6_5GpHat52OmaT8dowGHJJBVo46tJx-C6qWZnyxE,8233
+code2docs/generators/readme_gen.py,sha256=BE-XWic51yf9jihQEcBKn0CeLqOAbSVz5ss-suReCCw,8699
+code2docs/sync/__init__.py,sha256=MOTJYvJXPZF-4PS47lv-6bOc9J2ZoQGoIchp3vIuwrU,162
+code2docs/sync/differ.py,sha256=XqYDhxTM53AOCsbNrB_R3KVawg-an9YqUjPmyKsBS0I,4167
+code2docs/sync/updater.py,sha256=xlDX2YahgcUY1p0KkKrAmnWb1OEeePmBcYR_1sUrV4o,3100
+code2docs/sync/watcher.py,sha256=HvY4aK-WhCUrYEXoNFoQihBkith_JZHKwVKQV07CIJc,2392
+code2docs/templates/api_module.md.j2,sha256=mn8rH6YRlo1JIr0m8I6JkEvkhDCMOszfl9CEwEEZLAI,1485
+code2docs/templates/architecture.md.j2,sha256=kx_lECcC9FGHTEnhgPNVGIijDFXu5xFcm4wMHC85lNg,881
+code2docs/templates/example_usage.py.j2,sha256=G0mF7iLtisnsh-PfPTMLgVoNSDw6J-MqPndzMTtcuJk,225
+code2docs/templates/index.md.j2,sha256=pj56gwiLuXxV64xVYfzmtboMLyFKF-Kty01Ps0t37xM,653
+code2docs/templates/readme.md.j2,sha256=xG_vImqOGZKasRbQBuIunWQGaOEA_rjmtIpp8HJHm6U,2043
+code2docs-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+code2docs-0.1.1.dist-info/METADATA,sha256=cDRE_OuSQvV2wJWGb_Y-aSEOMDx1PtFYuoKpdSzt8dM,6620
+code2docs-0.1.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+code2docs-0.1.1.dist-info/entry_points.txt,sha256=ATamjPNo2CbTaAUN3LfK8qrnY3EQE9gE7lMDgPYhLdQ,49
+code2docs-0.1.1.dist-info/top_level.txt,sha256=L-O2M4M-NSiphgcKSfXFsC-t6PqziMl8Ef6tsNR2DaM,10
+code2docs-0.1.1.dist-info/RECORD,,

code2docs-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

code2docs-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code2docs = code2docs.cli:main