Metadata-Version: 2.1
Name: magnet-dpt-doc-generator
Version: 0.1.0
Summary: A Django app to generate Documentation for Django Project Template.
License: MIT
Author: Ignacio Munizaga
Author-email: ignacio.munizaga.t@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: anthropic (>=0.89.0,<0.90.0)
Requires-Dist: django (>=4.2)
Description-Content-Type: text/markdown

# magnet-dpt-doc-generator

Django management commands that use the Claude API (Anthropic) to automatically generate technical documentation for your project.

## Installation

```bash
pip install magnet-dpt-doc-generator
```

Add the app to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    "magnet_dpt_doc_generator",
]
```

## Requirements

An Anthropic API key is required. Set it in your `settings.py` or as an environment variable:

```python
# settings.py
ANTHROPIC_API_KEY = "sk-ant-..."
```

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

---

## Commands

### `generate_docs` — Generate SRS documentation

Scans your Django apps and generates a Markdown SRS (Software Requirements Specification) document per Python file using Claude. Output defaults to `docs/SRS/`.

```bash
# Document the whole project
python manage.py generate_docs

# Document specific apps only
python manage.py generate_docs --apps orders inventory

# Document a single file
python manage.py generate_docs --only orders/views.py

# Use extra directories as context (read by Claude, not documented)
python manage.py generate_docs --apps orders --context-dirs users core

# Custom output directory
python manage.py generate_docs --output ./my-docs

# Preview files that would be documented without calling the API
python manage.py generate_docs --dry-run

# Regenerate files that already exist
python manage.py generate_docs --force

# Reduce delay between API calls (default: 15s, use 0 for higher-tier plans)
python manage.py generate_docs --delay 2
```

**Options:**

| Option | Default | Description |
|---|---|---|
| `--output DIR` | `docs/SRS` | Output directory for `.md` files |
| `--apps APP [APP ...]` | *(whole project)* | Django apps to document |
| `--context-dirs DIR [DIR ...]` | — | Dirs Claude reads as context without documenting |
| `--only FILE` | — | Document a single file (relative to project root) |
| `--glossary FILE` | `docs/GLOSSARY.md` | Path to glossary file |
| `--dry-run` | `False` | List files without calling the API |
| `--force` | `False` | Overwrite existing `.md` files |
| `--delay SECONDS` | `15` | Pause between API calls |

---

### `generate_glossary` — Generate a domain glossary

Scans your apps in three phases — term extraction, definition from code evidence, and inference — to produce a `GLOSSARY.md` table of domain terms and acronyms.

```bash
# Generate glossary from scratch
python manage.py generate_glossary --apps orders inventory

# Add new terms without overwriting existing ones
python manage.py generate_glossary --apps orders inventory --update

# Custom output path
python manage.py generate_glossary --apps orders --output docs/MY_GLOSSARY.md
```

**Options:**

| Option | Default | Description |
|---|---|---|
| `--apps APP [APP ...]` | *(required)* | Django apps to scan |
| `--output FILE` | `docs/GLOSSARY.md` | Glossary output file |
| `--update` | `False` | Add new terms, preserve existing entries |
| `--delay SECONDS` | `15` | Pause between API calls |

**How it works (3 phases):**

1. **Phase 1 — Collect:** Scans `.py` and `.po` files to extract candidate domain terms.
2. **Phase 2 — Define:** Searches the same files for explicit definitions in code.
3. **Phase 3 — Infer:** Uses Claude to infer definitions for remaining undefined terms.

---

### `generate_brd` — Generate BRD documentation

Reads the SRS docs generated by `generate_docs` and produces BRD (Business Requirements Document) files organized by business flow. Output defaults to `docs/BRD/`.

**Run `generate_docs` first** — this command requires the SRS output as input.

```bash
# Discover business flows from the SRS
python manage.py generate_brd --discover

# Document a specific flow
python manage.py generate_brd --flow "Carga de Subestaciones"

# Document a flow inside a subdirectory
python manage.py generate_brd --flow "Carga de Subestaciones" --subdir "Extracción"

# Overwrite an existing flow file
python manage.py generate_brd --flow "Carga de Subestaciones" --force

# Regenerate README indexes only (no new flow files)
python manage.py generate_brd --reindex
python manage.py generate_brd --reindex --subdir "Extracción"
```

**Options:**

| Option | Default | Description |
|---|---|---|
| `--discover` | — | Analyze SRS and propose a list of business flows |
| `--flow NAME` | — | Name of the business flow to document |
| `--reindex` | — | Regenerate README index files without creating new flows |
| `--subdir NAME` | — | Subdirectory inside the BRD output dir |
| `--output DIR` | `docs/BRD` | BRD root output directory |
| `--srs-dir DIR` | `docs/SRS` | SRS input directory |
| `--glossary FILE` | `docs/GLOSSARY.md` | Path to glossary file |
| `--root-urls FILE` | `project/urls.py` | Root `urls.py` relative to `BASE_DIR` |
| `--srs-files FILE [FILE ...]` | — | Extra `.md` files appended to the SRS context |
| `--description TEXT` | — | Optional one-line description of the flow |
| `--force` | `False` | Overwrite an existing flow file |
| `--delay SECONDS` | `15` | Pause between API calls |

---

## Recommended workflow

```bash
# 1. Generate the glossary first (optional but improves doc quality)
python manage.py generate_glossary --apps myapp

# 2. Generate SRS documentation
python manage.py generate_docs --apps myapp

# 3. Discover business flows
python manage.py generate_brd --discover

# 4. Document each flow
python manage.py generate_brd --flow "My Flow Name"
```

---

## Configuration

All defaults can be overridden in your project's `settings.py` using the `MAGNET_DPT_` prefix:

```python
# settings.py

# Output paths (relative to BASE_DIR)
MAGNET_DPT_DOCS_OUTPUT_DIR = "docs/SRS"
MAGNET_DPT_GLOSSARY_PATH = "docs/GLOSSARY.md"
MAGNET_DPT_BRD_OUTPUT_DIR = "docs/BRD"

# Claude model settings
MAGNET_DPT_MODEL = "claude-sonnet-4-20250514"
MAGNET_DPT_MAX_TOKENS = 4096
MAGNET_DPT_MAX_CONTEXT_CHARS = 40_000

# Rate limiting (seconds between API calls)
# Free tier: ~15-20s | Build tier: ~2-3s | Higher tiers: 0
MAGNET_DPT_REQUEST_DELAY_SECONDS = 15
MAGNET_DPT_MAX_RETRIES = 3
MAGNET_DPT_RETRY_BACKOFF = 60  # multiplied by attempt number

# Scanning filters (provide as lists)
MAGNET_DPT_IGNORE_DIRS = ["__pycache__", ".git", ".venv", "venv", "node_modules", "migrations", "tests"]
MAGNET_DPT_IGNORE_PATHS = ["manage.py", "wsgi.py", "asgi.py", "settings.py", "admin.py",
                            "apps.py", "tests.py", "urls.py", "fixtures.py", "forms.py", "managers.py"]
MAGNET_DPT_INCLUDE_PATHS = []   # relative paths that override MAGNET_DPT_IGNORE_PATHS rules
MAGNET_DPT_SKIP_METHODS = ["__str__", "__repr__", "save", "delete", "get_queryset", ...]
```

| Setting | Default | Description |
|---|---|---|
| `MAGNET_DPT_DOCS_OUTPUT_DIR` | `docs/SRS` | Output dir for `generate_docs` |
| `MAGNET_DPT_BRD_OUTPUT_DIR` | `docs/BRD` | Output dir for `generate_brd` |
| `MAGNET_DPT_GLOSSARY_PATH` | `docs/GLOSSARY.md` | Shared glossary file |
| `MAGNET_DPT_MODEL` | `claude-sonnet-4-20250514` | Claude model used |
| `MAGNET_DPT_MAX_TOKENS` | `4096` | Max tokens per API response |
| `MAGNET_DPT_MAX_CONTEXT_CHARS` | `40000` | Max context chars sent to Claude (~10k tokens) |
| `MAGNET_DPT_REQUEST_DELAY_SECONDS` | `15` | Default delay between API calls |
| `MAGNET_DPT_MAX_RETRIES` | `3` | Retries on rate limit errors |
| `MAGNET_DPT_RETRY_BACKOFF` | `60` | Base wait per retry (seconds × attempt number) |
| `MAGNET_DPT_IGNORE_DIRS` | *(see above)* | Directory names excluded from scanning |
| `MAGNET_DPT_IGNORE_PATHS` | *(see above)* | Filenames/paths excluded from scanning |
| `MAGNET_DPT_INCLUDE_PATHS` | `[]` | Relative paths that override `IGNORE_PATHS` rules |
| `MAGNET_DPT_SKIP_METHODS` | *(see above)* | Method names omitted from documentation |

