magnet-dpt-doc-generator 0.1.0

A Django app to generate Documentation for Django Project Template.

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:

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.

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

# 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

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

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