# todocs

[![Version](https://img.shields.io/badge/version-0.1.1-blue)](https://github.com/wronai/todocs)
[![Python](https://img.shields.io/badge/python-3.10+-3776AB)](https://python.org)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Static-analysis documentation generator for project portfolios — WordPress-ready markdown articles **without LLM**.

## What it does

`todocs` scans a directory of projects and for each one:

1. **Extracts metadata** from `pyproject.toml`, `setup.py`, `setup.cfg`, `package.json`
2. **Analyzes code** using Python AST + [radon](https://radon.readthedocs.io/) for cyclomatic complexity and maintainability index
3. **Parses README** sections (description, installation, usage, features)
4. **Parses CHANGELOG** for recent version entries
5. **Detects tech stack** — languages, frameworks, build tools, CI/CD, Docker
6. **Scores maturity** (0–100) based on tests, docs, CI, packaging, complexity
7. **Generates WordPress-compatible markdown** articles with YAML frontmatter, badges, tables, and metrics

No API keys. No LLM calls. Pure static analysis.

## Installation

```bash
pip install todocs
```

Or from source:

```bash
git clone https://github.com/wronai/todocs.git
cd todocs
pip install -e .
```

## Usage

### Generate articles for all projects

```bash
todocs generate /path/to/organization --output articles/ --org-name WronAI
```

### Inspect a single project

```bash
todocs inspect /path/to/project --format json
todocs inspect /path/to/project --format markdown
```

### Full options

```bash
todocs generate /path/to/org \
  --output articles/ \
  --org-name "WronAI" \
  --org-url "https://github.com/wronai" \
  --exclude venv --exclude node_modules \
  --json-report report.json \
  --verbose
```

## Output Structure

```
articles/
├── _index.md          # Portfolio overview with all projects
├── allama.md          # Individual project article
├── broxeen.md
├── code2logic.md
├── ...
└── weekly.md
```

Each article includes:
- WordPress YAML frontmatter (title, slug, date, tags, category)
- Shields.io badges (version, maturity grade, language, SLOC)
- Overview from metadata + README
- Technology stack breakdown
- Architecture & key modules table
- Code metrics (complexity, maintainability, hotspots)
- Maturity checklist (tests, CI, docs, Docker, etc.)
- Dependencies list
- Recent changelog entries
- Installation & usage from README

## Python API

```python
from todocs import scan_organization, generate_articles

profiles = scan_organization("/path/to/org")
articles = generate_articles(profiles, "articles/", org_name="WronAI")
```

## How it compares to code2docs / weekly

| Feature | todocs | code2docs | weekly |
|---------|--------|-----------|--------|
| Scope | Multi-project portfolio | Single project docs | Single project quality |
| Output | WordPress articles | README, API docs | Quality reports |
| LLM required | No | Optional | No |
| Maturity scoring | Yes | No | Partial (checkers) |
| Tech stack detection | Yes | Partial | Partial |
| Changelog parsing | Yes | Yes | No |
| Cross-project index | Yes | No | Org scan mode |

`todocs` is designed to complement both — it can consume `.toon` files generated by `code2llm` and quality reports from `weekly` in future versions.

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## Author

Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)
