feat: major improvements — layout, cycles, integrations, usage examples, tests #1
188
README.md
188
README.md
@@ -1,68 +1,145 @@
|
||||
# ArchDoc
|
||||
|
||||
ArchDoc is a tool for automatically generating architecture documentation for Python projects. It analyzes your Python codebase and creates comprehensive documentation that helps developers understand the structure, dependencies, and key components of the project.
|
||||
|
||||
|
||||
|
||||
|
||||
**Automatic architecture documentation generator for Python projects.**
|
||||
|
||||
ArchDoc analyzes your Python codebase using AST parsing and generates comprehensive Markdown documentation covering module structure, dependencies, integration points, and critical hotspots.
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic Documentation Generation**: Automatically generates architecture documentation from Python source code
|
||||
- **AST-Based Analysis**: Uses Python AST to extract imports, definitions, and function calls
|
||||
- **Diff-Aware Updates**: Preserves manual content while updating generated sections
|
||||
- **Caching**: Caches analysis results for faster subsequent runs
|
||||
- **Configurable**: Highly configurable through `archdoc.toml`
|
||||
- **Template-Based Rendering**: Uses Handlebars templates for customizable output
|
||||
- **AST-Based Analysis** — Full Python AST traversal for imports, classes, functions, calls, and docstrings
|
||||
- **Dependency Graph** — Module-level and file-level dependency tracking with cycle detection
|
||||
- **Integration Detection** — Automatically identifies HTTP, database, and message queue integrations
|
||||
- **Diff-Aware Updates** — Preserves manually written sections while regenerating docs
|
||||
- **Caching** — Content-hash based caching for fast incremental regeneration
|
||||
- **Config Validation** — Comprehensive validation of `archdoc.toml` with helpful error messages
|
||||
- **Statistics** — Project-level stats: file counts, symbol counts, fan-in/fan-out metrics
|
||||
- **Consistency Checks** — Verify documentation stays in sync with code changes
|
||||
|
||||
## Installation
|
||||
|
||||
To install ArchDoc, you'll need Rust installed on your system. Then run:
|
||||
Requires Rust 1.85+:
|
||||
|
||||
```bash
|
||||
cargo install --path archdoc-cli
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Initialize Configuration
|
||||
|
||||
First, initialize the configuration in your project:
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize config in your Python project
|
||||
archdoc init
|
||||
```
|
||||
|
||||
This creates an `archdoc.toml` file with default settings.
|
||||
|
||||
### Generate Documentation
|
||||
|
||||
Generate architecture documentation for your project:
|
||||
|
||||
```bash
|
||||
# Generate architecture docs
|
||||
archdoc generate
|
||||
```
|
||||
|
||||
This will create documentation files in the configured output directory.
|
||||
# View project statistics
|
||||
archdoc stats
|
||||
|
||||
### Check Documentation Consistency
|
||||
|
||||
Verify that your documentation is consistent with the code:
|
||||
|
||||
```bash
|
||||
# Check docs are up-to-date
|
||||
archdoc check
|
||||
```
|
||||
|
||||
## Configuration
|
||||
## Commands
|
||||
|
||||
ArchDoc is configured through an `archdoc.toml` file. Here's an example configuration:
|
||||
### `archdoc generate`
|
||||
|
||||
Scans the project, analyzes Python files, and generates documentation:
|
||||
|
||||
```
|
||||
$ archdoc generate
|
||||
🔍 Scanning project...
|
||||
📂 Found 24 Python files in 6 modules
|
||||
🔬 Analyzing dependencies...
|
||||
📝 Generating documentation...
|
||||
✅ Generated docs/architecture/ARCHITECTURE.md
|
||||
✅ Generated 6 module docs
|
||||
```
|
||||
|
||||
Output includes:
|
||||
- **ARCHITECTURE.md** — Top-level overview with module index, dependency graph, and critical points
|
||||
- **Per-module docs** — Detailed documentation for each module with symbols, imports, and metrics
|
||||
- **Integration map** — HTTP, database, and queue integration points
|
||||
- **Critical points** — High fan-in/fan-out symbols and dependency cycles
|
||||
|
||||
### `archdoc stats`
|
||||
|
||||
Displays project statistics without generating docs:
|
||||
|
||||
```
|
||||
$ archdoc stats
|
||||
📊 Project Statistics
|
||||
Files: 24
|
||||
Modules: 6
|
||||
Classes: 12
|
||||
Functions: 47
|
||||
Imports: 89
|
||||
Edges: 134
|
||||
```
|
||||
|
||||
### `archdoc check`
|
||||
|
||||
Verifies documentation consistency with the current codebase:
|
||||
|
||||
```
|
||||
$ archdoc check
|
||||
✅ Documentation is up-to-date
|
||||
```
|
||||
|
||||
Returns non-zero exit code if docs are stale — useful in CI pipelines.
|
||||
|
||||
### `archdoc init`
|
||||
|
||||
Creates a default `archdoc.toml` configuration file:
|
||||
|
||||
```
|
||||
$ archdoc init
|
||||
✅ Created archdoc.toml with default settings
|
||||
```
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
ArchDoc is configured via `archdoc.toml`:
|
||||
|
||||
| Section | Key | Default | Description |
|
||||
|---------|-----|---------|-------------|
|
||||
| `project` | `root` | `"."` | Project root directory |
|
||||
| `project` | `out_dir` | `"docs/architecture"` | Output directory for generated docs |
|
||||
| `project` | `entry_file` | `"ARCHITECTURE.md"` | Main documentation file name |
|
||||
| `project` | `language` | `"python"` | Project language (only `python` supported) |
|
||||
| `scan` | `include` | `["src", "app", "tests"]` | Directories to scan |
|
||||
| `scan` | `exclude` | `[".venv", "__pycache__", ...]` | Directories to skip |
|
||||
| `scan` | `max_file_size` | `"10MB"` | Skip files larger than this (supports KB, MB, GB) |
|
||||
| `scan` | `follow_symlinks` | `false` | Whether to follow symbolic links |
|
||||
| `python` | `src_roots` | `["src", "."]` | Python source roots for import resolution |
|
||||
| `python` | `include_tests` | `true` | Include test files in analysis |
|
||||
| `python` | `parse_docstrings` | `true` | Extract docstrings from symbols |
|
||||
| `python` | `max_parse_errors` | `10` | Max parse errors before aborting |
|
||||
| `analysis` | `resolve_calls` | `true` | Resolve function call targets |
|
||||
| `analysis` | `detect_integrations` | `true` | Detect HTTP/DB/queue integrations |
|
||||
| `output` | `single_file` | `false` | Generate everything in one file |
|
||||
| `output` | `per_file_docs` | `true` | Generate per-module documentation |
|
||||
| `thresholds` | `critical_fan_in` | `20` | Fan-in threshold for critical symbols |
|
||||
| `thresholds` | `critical_fan_out` | `20` | Fan-out threshold for critical symbols |
|
||||
| `caching` | `enabled` | `true` | Enable analysis caching |
|
||||
| `caching` | `cache_dir` | `".archdoc/cache"` | Cache directory |
|
||||
| `caching` | `max_cache_age` | `"24h"` | Cache TTL (supports s, m, h, d, w) |
|
||||
|
||||
### Example Configuration
|
||||
|
||||
```toml
|
||||
[project]
|
||||
root = "."
|
||||
out_dir = "docs/architecture"
|
||||
entry_file = "ARCHITECTURE.md"
|
||||
language = "python"
|
||||
|
||||
[scan]
|
||||
include = ["src"]
|
||||
exclude = [".venv", "venv", "__pycache__", ".git", "dist", "build"]
|
||||
include = ["src", "app"]
|
||||
exclude = [".venv", "__pycache__", ".git"]
|
||||
max_file_size = "10MB"
|
||||
|
||||
[python]
|
||||
src_roots = ["src"]
|
||||
@@ -72,25 +149,46 @@ parse_docstrings = true
|
||||
[analysis]
|
||||
resolve_calls = true
|
||||
detect_integrations = true
|
||||
|
||||
[output]
|
||||
single_file = false
|
||||
per_file_docs = true
|
||||
create_directories = true
|
||||
integration_patterns = [
|
||||
{ type = "http", patterns = ["requests", "httpx", "aiohttp"] },
|
||||
{ type = "db", patterns = ["sqlalchemy", "psycopg", "sqlite3"] },
|
||||
{ type = "queue", patterns = ["celery", "kafka", "redis"] }
|
||||
]
|
||||
|
||||
[caching]
|
||||
enabled = true
|
||||
cache_dir = ".archdoc/cache"
|
||||
max_cache_age = "24h"
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Scanning**: ArchDoc scans your project directory for Python files based on the configuration
|
||||
2. **Parsing**: It parses each Python file using AST to extract structure and relationships
|
||||
3. **Analysis**: It analyzes the code to identify imports, definitions, and function calls
|
||||
4. **Documentation Generation**: It generates documentation using templates
|
||||
5. **Output**: It writes the documentation to files, preserving manual content
|
||||
1. **Scan** — Walks the project tree, filtering by include/exclude patterns
|
||||
2. **Parse** — Parses each Python file with a full AST traversal (via `rustpython-parser`)
|
||||
3. **Analyze** — Builds a project model with modules, symbols, edges, and metrics
|
||||
4. **Detect** — Identifies integration points (HTTP, DB, queues) and dependency cycles
|
||||
5. **Render** — Generates Markdown using Handlebars templates
|
||||
6. **Write** — Outputs files with diff-aware updates preserving manual sections
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
archdoc/
|
||||
├── archdoc-cli/ # CLI binary (commands, output formatting)
|
||||
│ └── src/
|
||||
│ ├── main.rs
|
||||
│ └── commands/ # generate, check, stats, init
|
||||
├── archdoc-core/ # Core library
|
||||
│ └── src/
|
||||
│ ├── config.rs # Config loading & validation
|
||||
│ ├── scanner.rs # File discovery
|
||||
│ ├── python_analyzer.rs # AST analysis
|
||||
│ ├── model.rs # Project IR (modules, symbols, edges)
|
||||
│ ├── cycle_detector.rs # Dependency cycle detection
|
||||
│ ├── renderer.rs # Markdown generation
|
||||
│ ├── writer.rs # File output with diff awareness
|
||||
│ └── cache.rs # Analysis caching
|
||||
└── test-project/ # Example Python project for testing
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -98,4 +196,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
This project is licensed under the MIT License — see the LICENSE file for details.
|
||||
|
||||
Reference in New Issue
Block a user