Arkasha/archdoc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: comprehensive README with badges, config reference, and command docs

Browse Source
This commit is contained in:
Arkasha
2026-02-15 03:28:22 +03:00
parent d237650f47
commit 73154e5865
1 changed files with 143 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
README.md
View File

@@ -1,68 +1,145 @@
# ArchDoc # 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. ![Rust](https://img.shields.io/badge/Rust-1.85%2B-orange?logo=rust)
![License](https://img.shields.io/badge/License-MIT-blue)
![Tests](https://img.shields.io/badge/Tests-50%20passing-brightgreen)
**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 ## Features
- **Automatic Documentation Generation**: Automatically generates architecture documentation from Python source code - **AST-Based Analysis** — Full Python AST traversal for imports, classes, functions, calls, and docstrings
- **AST-Based Analysis**: Uses Python AST to extract imports, definitions, and function calls - **Dependency Graph** — Module-level and file-level dependency tracking with cycle detection
- **Diff-Aware Updates**: Preserves manual content while updating generated sections - **Integration Detection** — Automatically identifies HTTP, database, and message queue integrations
- **Caching**: Caches analysis results for faster subsequent runs - **Diff-Aware Updates** — Preserves manually written sections while regenerating docs
- **Configurable**: Highly configurable through `archdoc.toml` - **Caching** — Content-hash based caching for fast incremental regeneration
- **Template-Based Rendering**: Uses Handlebars templates for customizable output - **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 ## Installation
To install ArchDoc, you'll need Rust installed on your system. Then run: Requires Rust 1.85+:
```bash ```bash
cargo install --path archdoc-cli cargo install --path archdoc-cli
``` ```
## Usage ## Quick Start
### Initialize Configuration
First, initialize the configuration in your project:
```bash ```bash
# Initialize config in your Python project
archdoc init archdoc init
```
This creates an `archdoc.toml` file with default settings. # Generate architecture docs
### Generate Documentation
Generate architecture documentation for your project:
```bash
archdoc generate archdoc generate
```
This will create documentation files in the configured output directory. # View project statistics
archdoc stats
### Check Documentation Consistency # Check docs are up-to-date
Verify that your documentation is consistent with the code:
```bash
archdoc check 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 ```toml
[project] [project]
root = "." root = "."
out_dir = "docs/architecture" out_dir = "docs/architecture"
entry_file = "ARCHITECTURE.md"
language = "python" language = "python"
[scan] [scan]
include = ["src"] include = ["src", "app"]
exclude = [".venv", "venv", "__pycache__", ".git", "dist", "build"] exclude = [".venv", "__pycache__", ".git"]
max_file_size = "10MB"
[python] [python]
src_roots = ["src"] src_roots = ["src"]
@@ -72,25 +149,46 @@ parse_docstrings = true
[analysis] [analysis]
resolve_calls = true resolve_calls = true
detect_integrations = true detect_integrations = true
integration_patterns = [
[output] { type = "http", patterns = ["requests", "httpx", "aiohttp"] },
single_file = false { type = "db", patterns = ["sqlalchemy", "psycopg", "sqlite3"] },
per_file_docs = true { type = "queue", patterns = ["celery", "kafka", "redis"] }
create_directories = true ]
[caching] [caching]
enabled = true enabled = true
cache_dir = ".archdoc/cache"
max_cache_age = "24h" max_cache_age = "24h"
``` ```
## How It Works ## How It Works
1. **Scanning**: ArchDoc scans your project directory for Python files based on the configuration 1. **Scan** — Walks the project tree, filtering by include/exclude patterns
2. **Parsing**: It parses each Python file using AST to extract structure and relationships 2. **Parse** — Parses each Python file with a full AST traversal (via `rustpython-parser`)
3. **Analysis**: It analyzes the code to identify imports, definitions, and function calls 3. **Analyze** — Builds a project model with modules, symbols, edges, and metrics
4. **Documentation Generation**: It generates documentation using templates 4. **Detect** — Identifies integration points (HTTP, DB, queues) and dependency cycles
5. **Output**: It writes the documentation to files, preserving manual content 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 ## Contributing
@@ -98,4 +196,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
## License ## 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.