magnet-dpt-doc-generator

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

Installation

pip install magnet-dpt-doc-generator

Add the app to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "magnet_dpt_doc_generator",
]

Requirements

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

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

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/.

# 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:

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.

# 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:

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.

# 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:

Recommended workflow

# 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:

# 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", ...]