Add documentation templates
This commit is contained in:
Tuan-Dat Tran
100
docs/templates/AGENTS.template.md
vendored
Normal file
100
docs/templates/AGENTS.template.md
vendored
Normal file
@@ -0,0 +1,100 @@
|
||||
# AGENTS.md
|
||||
|
||||
Guide for AI assistants working on this codebase.
|
||||
|
||||
## Build/Verify Commands
|
||||
|
||||
This project has no external dependencies or test framework.
|
||||
|
||||
```bash
|
||||
# No lint/typecheck commands currently
|
||||
# Verify scripts work by running them:
|
||||
python hydrate.py --help
|
||||
python scripts/analyze_decks.py --help
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- **Language:** Python 3 (stdlib only, no external packages)
|
||||
- **Formatting:** 4-space indent, max line length ~100
|
||||
- **Imports:** Standard library only (argparse, json, pathlib, urllib, re, sys, os, time)
|
||||
- **CLI:** Use `argparse` with subparsers for multi-command tools
|
||||
- **Error handling:** Print to stderr, use sys.exit(1) for failures
|
||||
- **Docstrings:** Triple-quoted at module and function level with usage examples
|
||||
- **Type hints:** Optional but encouraged for complex functions
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── hydrate.py # Main CLI - fetches card data from Scryfall
|
||||
├── card_cache.json # Local cache of Scryfall card data
|
||||
├── deck_analysis.json # Analysis output
|
||||
├── collection/ # Raw decklist text files
|
||||
├── collection_hydrated/ # Enriched card data by type
|
||||
│ ├── deck.json # All cards combined
|
||||
│ ├── commander.json
|
||||
│ ├── creatures.json
|
||||
│ ├── instants.json
|
||||
│ ├── sorceries.json
|
||||
│ ├── artifacts.json
|
||||
│ ├── enchantments.json
|
||||
│ ├── lands.json
|
||||
│ └── planeswalkers.json
|
||||
├── decks/ # Deck definitions (JSON)
|
||||
│ └── <deck_name>.json # name, commander, colors, archetype, cards
|
||||
├── scripts/
|
||||
│ ├── analyze_decks.py # Find upgrade options for decks
|
||||
│ ├── find_synergies.py # Search for synergistic cards
|
||||
│ ├── parse_deck.py # Parse text decklists to JSON
|
||||
│ └── deck_report.py # Generate markdown reports
|
||||
└── docs/
|
||||
└── templates/ # Documentation templates
|
||||
```
|
||||
|
||||
## Data Formats
|
||||
|
||||
### Deck JSON (`decks/*.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Deck Name",
|
||||
"commander": "Commander Name",
|
||||
"colors": ["U", "G", "W"],
|
||||
"archetype": "Theme Description",
|
||||
"cards": {
|
||||
"Card Name": count,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Card Data (`collection_hydrated/*.json`)
|
||||
|
||||
Array of card objects with Scryfall fields:
|
||||
- `name`, `mana_cost`, `cmc`, `colors`, `color_identity`
|
||||
- `type_line`, `oracle_text`, `power`, `toughness`, `loyalty`
|
||||
- `scryfall_uri`, `count`
|
||||
|
||||
## Extension Guide
|
||||
|
||||
### Adding a New Deck
|
||||
|
||||
1. Create `decks/<name>.json` with required fields
|
||||
2. Run `python scripts/update_docs.py` to regenerate documentation
|
||||
|
||||
### Adding a New Script
|
||||
|
||||
1. Create `scripts/<name>.py` with argparse CLI
|
||||
2. Follow existing patterns: `load_collection()`, argparse with --help
|
||||
3. Update README template with usage example
|
||||
4. Run `python scripts/update_docs.py`
|
||||
|
||||
### Modifying Deck Analysis
|
||||
|
||||
- `scripts/analyze_decks.py`: Core logic for finding upgrades
|
||||
- Color identity matching uses `color_identity` field from Scryfall
|
||||
- Cards are categorized by `type_line`
|
||||
|
||||
## Current Decks
|
||||
|
||||
{{DECK_TABLE}}
|
||||
77
docs/templates/README.template.md
vendored
Normal file
77
docs/templates/README.template.md
vendored
Normal file
@@ -0,0 +1,77 @@
|
||||
# MTG EDH Deck Manager
|
||||
|
||||
Command-line toolkit for managing Magic: The Gathering Commander (EDH) decks using the Scryfall API.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
git clone <repo-url>
|
||||
cd Decks
|
||||
```
|
||||
|
||||
No dependencies required - pure Python 3 standard library.
|
||||
|
||||
## Usage
|
||||
|
||||
### Hydrate a Collection
|
||||
|
||||
Fetch card data from Scryfall for a decklist:
|
||||
|
||||
```bash
|
||||
python hydrate.py hydrate collection/decklist.txt -o collection_hydrated/ -c card_cache.json
|
||||
```
|
||||
|
||||
### Create a New Deck
|
||||
|
||||
```bash
|
||||
python hydrate.py new my_deck
|
||||
```
|
||||
|
||||
### Analyze Decks
|
||||
|
||||
Find upgrade options from your collection:
|
||||
|
||||
```bash
|
||||
python scripts/analyze_decks.py --collection collection_hydrated/deck.json --deck-dir decks/
|
||||
```
|
||||
|
||||
### Find Synergies
|
||||
|
||||
Search for cards by keywords, colors, and type:
|
||||
|
||||
```bash
|
||||
# Find landfall cards in Simic colors
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G --keywords landfall
|
||||
|
||||
# Find Bird creatures in Bant colors
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G W --creature-type Bird
|
||||
|
||||
# Find instants with CMC 2 or less
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --type instant --cmc-max 2
|
||||
```
|
||||
|
||||
### Generate Reports
|
||||
|
||||
```bash
|
||||
python scripts/deck_report.py --collection collection_hydrated/deck.json --decks-dir decks/ --output report.md
|
||||
```
|
||||
|
||||
## Decks
|
||||
|
||||
{{DECK_TABLE}}
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Import** - Place text decklists in `collection/`
|
||||
2. **Hydrate** - Run `hydrate.py` to fetch Scryfall data → `collection_hydrated/`
|
||||
3. **Define** - Create deck JSON files in `decks/`
|
||||
4. **Analyze** - Run `analyze_decks.py` to find upgrade options
|
||||
5. **Report** - Use `deck_report.py` for markdown summaries
|
||||
|
||||
## Collection Stats
|
||||
|
||||
{{COLLECTION_STATS}}
|
||||
|
||||
---
|
||||
|
||||
*This file is auto-generated. Edit `docs/templates/README.template.md` instead.*
|
||||
Reference in New Issue
Block a user