first commit

2026-03-24 19:36:04 +02:00
commit 5493e927de
15 changed files with 1845 additions and 0 deletions
@@ -0,0 +1,143 @@
+# Crossword Puzzle Generator for Amazon KDP
+
+A Python CLI tool that reads words and clues from a CSV file, generates crossword puzzle grids, and outputs a print-ready PDF book formatted for Amazon KDP upload.
+
+## Quick Start
+
+```bash
+# Set up a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Generate a crossword book from the sample data
+python main.py --input sample_words.csv \
+               --output my_book.pdf \
+               --puzzles 20 \
+               --title "My Crossword Book" \
+               --author "Your Name"
+```
+
+## Input Format
+
+A CSV file with at minimum two columns — `word` and `clue`:
+
+```csv
+word,clue
+PYTHON,"A large snake, or a programming language"
+GRID,"A network of lines that cross each other"
+PUZZLE,"A game or problem that tests ingenuity"
+```
+
+Optional columns:
+
+| Column | Purpose |
+|--------|---------|
+| `difficulty` | Group words into easy/medium/hard puzzles |
+| `category` | Generate themed puzzles (e.g. "Animals", "Science") |
+
+Words are automatically normalised to uppercase. Accented characters are stripped (e.g. `café` → `CAFE`). Duplicates, words shorter than 3 letters, and words containing non-alpha characters are rejected with a warning.
+
+## CLI Reference
+
+```
+Usage: main.py [OPTIONS]
+
+  Generate a KDP-ready crossword puzzle book from a CSV word list.
+```
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--input FILE` | Path to a CSV file with `word,clue` columns |
+
+### Optional
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--output TEXT` | `output.pdf` | Output PDF file path |
+| `--puzzles INTEGER` | `20` | Number of crossword puzzles to generate |
+| `--grid-size INTEGER` | `13` | Grid dimensions (e.g. `15` for a 15×15 grid) |
+| `--trim-size CHOICE` | `8.5x11` | KDP page trim size — one of `8.5x11`, `6x9`, `8x10` |
+| `--title TEXT` | `Crossword Puzzles` | Book title for the cover page |
+| `--author TEXT` | *(empty)* | Author name |
+| `--words-per-puzzle INTEGER` | `20` | Target number of words per puzzle |
+| `--solutions-at-end` | off | Group all solution pages at the back of the book |
+| `--seed INTEGER` | *(random)* | Random seed for reproducible output |
+| `--no-toc` | off | Omit the table of contents page |
+| `--no-instructions` | off | Omit the how-to-solve instructions page |
+| `-v, --verbose` | off | Enable verbose/debug logging |
+| `--help` | | Show help and exit |
+
+### Examples
+
+Generate a 50-puzzle book in 6×9 format with solutions at the back:
+
+```bash
+python main.py --input words.csv \
+               --output crossword_book.pdf \
+               --puzzles 50 \
+               --grid-size 15 \
+               --trim-size 6x9 \
+               --title "The Ultimate Crossword Book" \
+               --author "Jane Doe" \
+               --solutions-at-end \
+               --seed 42
+```
+
+Quick 10-puzzle book with a smaller grid and no front matter extras:
+
+```bash
+python main.py --input words.csv \
+               --output quick_puzzles.pdf \
+               --puzzles 10 \
+               --grid-size 10 \
+               --no-toc \
+               --no-instructions
+```
+
+## Book Structure
+
+Each generated PDF contains:
+
+1. **Title page** — book title and author
+2. **Copyright page** — auto-generated with the current year
+3. **Table of contents** — puzzle numbers mapped to page numbers (optional)
+4. **Instructions page** — "How to Solve" guide (optional)
+5. **Puzzle pages** — empty grid with numbered cells, black squares, and clues in two columns
+6. **Solution pages** — filled grid with all letters visible
+
+Page numbering starts after the front matter. Gutter (inside) margins are automatically calculated based on total page count per KDP specifications.
+
+## Project Structure
+
+```
+crossword-kdp-generator/
+├── main.py              # CLI entry point
+├── csv_reader.py        # CSV parsing and validation
+├── generator.py         # Crossword grid generation algorithm
+├── renderer.py          # PDF grid and clue rendering
+├── kdp_format.py        # KDP page layout and front matter
+├── models.py            # Data classes
+├── requirements.txt     # Dependencies
+├── sample_words.csv     # Example input (50 words, 5 categories)
+├── PLAN.md              # Implementation plan
+└── README.md            # This file
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [ReportLab](https://www.reportlab.com/) | PDF generation |
+| [Click](https://click.palletsprojects.com/) | CLI argument parsing |
+
+## KDP Notes
+
+- **Trim sizes:** 8.5"×11", 6"×9", 8"×10"
+- **Margins:** Outside 0.5", gutter auto-calculated (0.375"–0.875" based on page count)
+- **Page count:** KDP requires 24–828 pages; the tool warns if below minimum
+- **Bleed:** Not needed for puzzle books (no content extends to the page edge)