144 lines
4.8 KiB
Markdown
144 lines
4.8 KiB
Markdown
# 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)
|