refactor(docs): code analysis engine

changes:
  - file: _registry_adapters.py
    area: docs
    modified: [ReadmeGeneratorAdapter, MkDocsAdapter, ContributingAdapter, ExamplesAdapter]
  - file: contributing_gen.py
    area: docs
    modified: [_render_setup, ContributingGenerator]
  - file: getting_started_gen.py
    area: docs
    modified: [GettingStartedGenerator, _render_installation]

dependencies:
  flow: "_registry_adapters→contributing_gen"
  - _registry_adapters.py -> getting_started_gen.py
  - _registry_adapters.py -> contributing_gen.py

stats:
  lines: "+12055/-11916 (net +139)"
  files: 15
  complexity: "+62% complexity (monitor)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.3] - 2026-03-08
+
+### Docs
+- Update code2docs/README.md
+- Update code2docs/project/context.md
+- Update docs/architecture.md
+- Update project/context.md
+
+### Test
+- Update tests/project/dashboard.html
+- Update tests/project/project.yaml
+
+### Other
+- Update code2docs/generators/_registry_adapters.py
+- Update code2docs/generators/contributing_gen.py
+- Update code2docs/generators/getting_started_gen.py
+- Update code2docs/project/analysis.json
+- Update code2docs/project/analysis.toon
+- Update code2docs/project/analysis.yaml
+- Update code2docs/project/calls.mmd
+- Update code2docs/project/dashboard.html
+- Update code2docs/project/flow.mmd
+- Update code2docs/project/flow.toon
+- ... and 11 more files
+
 ## [3.0.2] - 2026-03-08
 
 ### Docs

README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-3.0.2-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.3-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.
 
@@ -140,7 +140,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.2-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

VERSION

@@ -1 +1 @@
-3.0.2
+3.0.3

code2docs/README.md

@@ -139,6 +139,189 @@ Content outside the markers is preserved when regenerating. Enable this with `sy
 
 ## Architecture
 
+```
+code2docs/
+├── registry├── llm_helper├── code2docs/    ├── updater├── sync/    ├── watcher    ├── differ    ├── quickstart    ├── advanced_usage    ├── markdown    ├── badges├── base├── formatters/    ├── toc    ├── coverage_gen    ├── _source_links    ├── readme_gen    ├── depgraph_gen    ├── config_docs_gen    ├── getting_started_gen    ├── changelog_gen├── generators/    ├── code2llm_gen    ├── module_docs_gen    ├── api_reference_gen    ├── mkdocs_gen    ├── examples_gen    ├── _registry_adapters    ├── api_changelog_gen    ├── contributing_gen    ├── architecture_gen├── analyzers/├── cli├── config    ├── project_scanner    ├── dependency_scanner    ├── docstring_extractor    ├── endpoint_detector```
+
+## API Overview
+
+### Classes
+
+- **`GeneratorRegistry`** — Registry of documentation generators.
+- **`LLMHelper`** — Thin wrapper around litellm for documentation generation.
+- **`Updater`** — Apply selective documentation updates based on detected changes.
+- **`ChangeInfo`** — Describes a detected change.
+- **`Differ`** — Detect changes between current source and previous state.
+- **`MarkdownFormatter`** — Helper for constructing Markdown documents.
+- **`GenerateContext`** — Shared context passed to all generators during a run.
+- **`BaseGenerator`** — Abstract base for all documentation generators.
+- **`CoverageGenerator`** — Generate docs/coverage.md — docstring coverage report.
+- **`SourceLinker`** — Build source-code links (relative paths + optional GitHub/GitLab URLs).
+- **`ReadmeGenerator`** — Generate README.md from AnalysisResult.
+- **`DepGraphGenerator`** — Generate docs/dependency-graph.md with Mermaid diagrams.
+- **`ConfigDocsGenerator`** — Generate docs/configuration.md from Code2DocsConfig dataclass.
+- **`GettingStartedGenerator`** — Generate docs/getting-started.md from entry points and dependencies.
+- **`ChangelogEntry`** — A single changelog entry.
+- **`ChangelogGenerator`** — Generate CHANGELOG.md from git log and analysis diff.
+- **`Code2LlmGenerator`** — Generate code2llm analysis files in project/ directory.
+- **`ModuleDocsGenerator`** — Generate docs/modules.md — consolidated module documentation.
+- **`ApiReferenceGenerator`** — Generate docs/api.md — consolidated API reference.
+- **`MkDocsGenerator`** — Generate mkdocs.yml from the docs/ directory structure.
+- **`ExamplesGenerator`** — Generate examples/ — usage examples from public API signatures.
+- **`ReadmeGeneratorAdapter`** — —
+- **`ApiReferenceAdapter`** — —
+- **`ModuleDocsAdapter`** — —
+- **`ArchitectureAdapter`** — —
+- **`DepGraphAdapter`** — —
+- **`CoverageAdapter`** — —
+- **`ApiChangelogAdapter`** — —
+- **`ExamplesAdapter`** — —
+- **`MkDocsAdapter`** — —
+- **`GettingStartedAdapter`** — —
+- **`ConfigDocsAdapter`** — —
+- **`ContributingAdapter`** — —
+- **`Code2LlmAdapter`** — Adapter for code2llm analysis generation.
+- **`ApiChange`** — A single API change between two analysis snapshots.
+- **`ApiChangelogGenerator`** — Generate API changelog by diffing current analysis with a saved snapshot.
+- **`ContributingGenerator`** — Generate CONTRIBUTING.md by detecting dev tools from pyproject.toml.
+- **`ArchitectureGenerator`** — Generate docs/architecture.md — architecture overview with diagrams.
+- **`DefaultGroup`** — Click Group that routes unknown subcommands to 'generate'.
+- **`ReadmeConfig`** — Configuration for README generation.
+- **`DocsConfig`** — Configuration for docs/ generation.
+- **`ExamplesConfig`** — Configuration for examples/ generation.
+- **`SyncConfig`** — Configuration for synchronization.
+- **`Code2LlmConfig`** — Configuration for code2llm analysis generation.
+- **`LLMConfig`** — Configuration for optional LLM-assisted documentation generation.
+- **`Code2DocsConfig`** — Main configuration for code2docs.
+- **`ProjectScanner`** — Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults.
+- **`DependencyInfo`** — Information about a project dependency.
+- **`ProjectDependencies`** — All detected project dependencies.
+- **`DependencyScanner`** — Scan and parse project dependency files.
+- **`DocstringInfo`** — Parsed docstring with sections.
+- **`DocstringExtractor`** — Extract and parse docstrings from AnalysisResult.
+- **`Endpoint`** — Represents a detected web endpoint.
+- **`EndpointDetector`** — Detects web endpoints from decorator patterns in source code.
+
+### Functions
+
+- `start_watcher(project_path, config)` — Start watching project for file changes and auto-resync docs.
+- `generate_badges(project_name, badge_types, stats, deps)` — Generate shields.io badge Markdown strings.
+- `generate_toc(markdown_content, max_depth)` — Generate a table of contents from Markdown headings.
+- `extract_headings(content, max_depth)` — Extract headings from Markdown content.
+- `generate_readme(project_path, output, sections, sync_markers)` — Convenience function to generate a README.
+- `generate_docs(project_path, config)` — High-level function to generate all documentation.
+- `parse_gitignore(project_path)` — Parse .gitignore file and return list of patterns to exclude.
+- `generate_code2llm_analysis(project_path, config)` — Convenience function to generate code2llm analysis.
+- `main()` — code2docs — Auto-generate project documentation from source code.
+- `generate(project_path, config_path, readme_only, sections)` — Generate documentation (default command).
+- `sync(project_path, config_path, verbose, dry_run)` — Synchronize documentation with source code changes.
+- `watch(project_path, config_path, verbose)` — Watch for file changes and auto-regenerate docs.
+- `init(project_path, output)` — Initialize code2docs.yaml configuration file.
+- `check(project_path, config_path, target)` — Health check — verify documentation completeness.
+- `diff(project_path, config_path)` — Preview what would change without writing anything.
+- `analyze_and_document(project_path, config)` — Convenience function: analyze a project in one call.
+
+
+## Project Structure
+
+📄 `__main__`
+📦 `analyzers`
+📄 `analyzers.dependency_scanner` (6 functions, 3 classes)
+📄 `analyzers.docstring_extractor` (10 functions, 2 classes)
+📄 `analyzers.endpoint_detector` (3 functions, 2 classes)
+📄 `analyzers.project_scanner` (4 functions, 1 classes)
+📄 `base` (3 functions, 2 classes)
+📄 `cli` (14 functions, 1 classes)
+📦 `code2docs` (1 functions)
+📄 `config` (5 functions, 7 classes)
+📄 `examples.advanced_usage`
+📄 `examples.quickstart`
+📦 `formatters`
+📄 `formatters.badges` (2 functions)
+📄 `formatters.markdown` (13 functions, 1 classes)
+📄 `formatters.toc` (3 functions)
+📦 `generators` (1 functions)
+📄 `generators._registry_adapters` (26 functions, 13 classes)
+📄 `generators._source_links` (6 functions, 1 classes)
+📄 `generators.api_changelog_gen` (9 functions, 2 classes)
+📄 `generators.api_reference_gen` (7 functions, 1 classes)
+📄 `generators.architecture_gen` (10 functions, 1 classes)
+📄 `generators.changelog_gen` (6 functions, 2 classes)
+📄 `generators.code2llm_gen` (6 functions, 1 classes)
+📄 `generators.config_docs_gen` (4 functions, 1 classes)
+📄 `generators.contributing_gen` (8 functions, 1 classes)
+📄 `generators.coverage_gen` (7 functions, 1 classes)
+📄 `generators.depgraph_gen` (9 functions, 1 classes)
+📄 `generators.examples_gen` (14 functions, 1 classes)
+📄 `generators.getting_started_gen` (8 functions, 1 classes)
+📄 `generators.mkdocs_gen` (4 functions, 1 classes)
+📄 `generators.module_docs_gen` (9 functions, 1 classes)
+📄 `generators.readme_gen` (18 functions, 1 classes)
+📄 `llm_helper` (7 functions, 1 classes)
+📄 `registry` (4 functions, 1 classes)
+📦 `sync`
+📄 `sync.differ` (7 functions, 2 classes)
+📄 `sync.updater` (2 functions, 1 classes)
+📄 `sync.watcher` (1 functions)
+
+## Requirements
+
+
+
+## Contributing
+
+**Contributors:**
+- Tom Softreck <tom@sapletta.com>
+- Tom Sapletta <tom-sapletta-com@users.noreply.github.com>
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/wronai/code2docs
+cd code2docs
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+## Documentation
+
+- 📖 [Full Documentation](https://github.com/wronai/code2docs/tree/main/docs) — API reference, module docs, architecture
+- 🚀 [Getting Started](https://github.com/wronai/code2docs/blob/main/docs/getting-started.md) — Quick start guide
+- 📚 [API Reference](https://github.com/wronai/code2docs/blob/main/docs/api.md) — Complete API documentation
+- 🔧 [Configuration](https://github.com/wronai/code2docs/blob/main/docs/configuration.md) — Configuration options
+- 💡 [Examples](./examples) — Usage examples and code samples
+
+### Generated Files
+
+| Output | Description | Link |
+|--------|-------------|------|
+| `README.md` | Project overview (this file) | — |
+| `docs/api.md` | Consolidated API reference | [View](./docs/api.md) |
+| `docs/modules.md` | Module reference with metrics | [View](./docs/modules.md) |
+| `docs/architecture.md` | Architecture with diagrams | [View](./docs/architecture.md) |
+| `docs/dependency-graph.md` | Dependency graphs | [View](./docs/dependency-graph.md) |
+| `docs/coverage.md` | Docstring coverage report | [View](./docs/coverage.md) |
+| `docs/getting-started.md` | Getting started guide | [View](./docs/getting-started.md) |
+| `docs/configuration.md` | Configuration reference | [View](./docs/configuration.md) |
+| `docs/api-changelog.md` | API change tracking | [View](./docs/api-changelog.md) |
+| `CONTRIBUTING.md` | Contribution guidelines | [View](./CONTRIBUTING.md) |
+| `examples/` | Usage examples | [Browse](./examples) |
+| `mkdocs.yml` | MkDocs configuration | — |
+
+<!-- code2docs:end -->
+```
+
+Content outside the markers is preserved when regenerating. Enable this with `sync_markers: true` in your configuration.
+
+## Architecture
+
 ```
 code2docs/
 ├── registry├── llm_helper├── code2docs/    ├── updater├── sync/    ├── watcher    ├── differ    ├── quickstart    ├── advanced_usage    ├── markdown    ├── badges    ├── toc├── formatters/├── base    ├── readme_gen    ├── coverage_gen    ├── _source_links    ├── depgraph_gen    ├── getting_started_gen    ├── config_docs_gen    ├── changelog_gen├── generators/    ├── code2llm_gen    ├── module_docs_gen    ├── api_reference_gen    ├── mkdocs_gen    ├── _registry_adapters    ├── examples_gen    ├── api_changelog_gen    ├── contributing_gen    ├── architecture_gen├── analyzers/├── cli├── config    ├── project_scanner    ├── docstring_extractor    ├── dependency_scanner    ├── endpoint_detector```

code2docs/__init__.py

@@ -5,7 +5,7 @@
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = "3.0.2"
+__version__ = "3.0.3"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

code2docs/generators/_registry_adapters.py

@@ -25,7 +25,12 @@ def run(self, ctx: GenerateContext) -> Optional[str]:
             preview = content[:500] + "..." if len(content) > 500 else content
             click.echo(preview)
             return None
-        readme_path = ctx.project / self.config.readme_output
+        # Use docs_dir if readme_output is a simple filename, otherwise respect the path
+        readme_output = Path(self.config.readme_output)
+        if readme_output.parent == Path("."):
+            readme_path = ctx.docs_dir / readme_output.name
+        else:
+            readme_path = ctx.project / readme_output
         gen.write(str(readme_path), content)
         return f"✅ {readme_path.relative_to(ctx.project)}"
 
@@ -141,7 +146,7 @@ def run(self, ctx: GenerateContext) -> Optional[str]:
         files = gen.generate_all()
         if ctx.dry_run:
             return f"[dry-run] examples/ ({len(files)} files)"
-        examples_dir = ctx.project / "examples"
+        examples_dir = ctx.docs_dir / "examples"
         gen.write_all(str(examples_dir), files)
         return f"✅ examples/ ({len(files)} files)"
 
@@ -158,7 +163,7 @@ def run(self, ctx: GenerateContext) -> Optional[str]:
         content = gen.generate(str(ctx.docs_dir))
         if ctx.dry_run:
             return "[dry-run] mkdocs.yml"
-        gen.write(str(ctx.project / "mkdocs.yml"), content)
+        gen.write(str(ctx.docs_dir / "mkdocs.yml"), content)
         return "✅ mkdocs.yml"
 
 
@@ -208,7 +213,8 @@ def run(self, ctx: GenerateContext) -> Optional[str]:
         content = gen.generate()
         if ctx.dry_run:
             return "[dry-run] CONTRIBUTING.md"
-        (ctx.project / "CONTRIBUTING.md").write_text(content, encoding="utf-8")
+        ctx.docs_dir.mkdir(parents=True, exist_ok=True)
+        (ctx.docs_dir / "CONTRIBUTING.md").write_text(content, encoding="utf-8")
         return "✅ CONTRIBUTING.md"
 
 

code2docs/generators/contributing_gen.py

@@ -54,10 +54,11 @@ def _detect_dev_tools(self) -> Dict[str, bool]:
     def _render_setup(self, tools: Dict[str, bool]) -> str:
         """Render development setup instructions."""
         project = self.config.project_name or "project"
+        repo_url = self.config.repo_url or "<repository-url>"
         lines = [
             "## Development Setup\n",
             "```bash",
-            f"git clone <repository-url>",
+            f"git clone {repo_url}",
             f"cd {project}",
             "python -m venv .venv",
             "source .venv/bin/activate  # or .venv\\Scripts\\activate on Windows",

code2docs/generators/getting_started_gen.py

@@ -59,14 +59,15 @@ def _render_installation(self) -> str:
         dep_scanner = DependencyScanner()
         deps = dep_scanner.scan(self.result.project_path)
         cmd = deps.install_command or f"pip install {self.config.project_name or '.'}"
+        repo_url = self.config.repo_url or "<repository-url>"
         lines = [
             "## Installation\n",
             "```bash",
             cmd,
             "```\n",
             "To install from source:\n",
             "```bash",
-            "git clone <repository-url>",
+            f"git clone {repo_url}",
             f"cd {self.config.project_name or 'project'}",
             "pip install -e .",
             "```",

code2docs/project/analysis.json

@@ -167,9 +167,9 @@ CLASSES:
   ExamplesConfig                                            0m  CC̄=0.0   max=0.0 
   SyncConfig                                                0m  CC̄=0.0   max=0.0 
   Code2LlmConfig                                            0m  CC̄=0.0   max=0.0 
-  DocstringInfo                                             0m  CC̄=0.0   max=0.0 
   DependencyInfo                                            0m  CC̄=0.0   max=0.0 
   ProjectDependencies                                       0m  CC̄=0.0   max=0.0 
+  DocstringInfo                                             0m  CC̄=0.0   max=0.0 
   Endpoint                                                  0m  CC̄=0.0   max=0.0 
 
 D:
@@ -262,15 +262,6 @@ Thi...
     e: ContributingGenerator
     ContributingGenerator  # Generate CONTRIBUTING.md by detecting dev tools from pyproje...
       __init__(2)  CC=1.0
-  analyzers/docstring_extractor.py:
-    e: DocstringInfo,DocstringExtractor
-    DocstringInfo  # Parsed docstring with sections....
-    DocstringExtractor  # Extract and parse docstrings from AnalysisResult....
-      extract_all(1)  CC=5.0
-        → parse(1)  CC=2.0
-        → _extract_summary(0)  CC=2.0
-        → _parse_sections(2)  CC=8.0
-        → _classify_section(0)  CC=5.0
   analyzers/dependency_scanner.py:
     e: DependencyInfo,ProjectDependencies,DependencyScanner
     DependencyInfo  # Information about a project dependency....
@@ -282,6 +273,15 @@ Thi...
         → _parse_dep_string(0)  CC=2.0
         → _parse_setup_py(1)  CC=4.0
         → _parse_requirements_txt(1)  CC=5.0
+  analyzers/docstring_extractor.py:
+    e: DocstringInfo,DocstringExtractor
+    DocstringInfo  # Parsed docstring with sections....
+    DocstringExtractor  # Extract and parse docstrings from AnalysisResult....
+      extract_all(1)  CC=5.0
+        → parse(1)  CC=2.0
+        → _extract_summary(0)  CC=2.0
+        → _parse_sections(2)  CC=8.0
+        → _classify_section(0)  CC=5.0
   llm_helper.py:
     e: LLMHelper,_get_litellm
     LLMHelper  # Thin wrapper around litellm for documentation generation.