# EPUB Builder Script Build an EPUB ebook from the Claude How-To markdown files. ## Features - Organizes chapters by folder structure (01-slash-commands, 02-memory, etc.) - Renders Mermaid diagrams as PNG images via Kroki.io API - Async concurrent fetching - renders all diagrams in parallel - Generates a cover image from the project logo - Converts internal markdown links to EPUB chapter references - Strict error mode - fails if any diagram cannot be rendered ## Requirements - Python 3.10+ - [uv](https://github.com/astral-sh/uv) - Internet connection for Mermaid diagram rendering ## Quick Start ```bash # Simplest way - uv handles everything uv run scripts/build_epub.py ``` ## Development Setup ```bash # Create virtual environment uv venv # Activate and install dependencies source .venv/bin/activate uv pip install -r requirements-dev.txt # Run tests pytest scripts/tests/ -v # Run the script python scripts/build_epub.py ``` ## Command-Line Options ``` usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose] [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT] options: -h, --help show this help message and exit --root, -r ROOT Root directory (default: repo root) --output, -o OUTPUT Output path (default: claude-howto-guide.epub) --verbose, -v Enable verbose logging --timeout TIMEOUT API timeout in seconds (default: 30) --max-concurrent N Max concurrent requests (default: 10) ``` ## Examples ```bash # Build with verbose output uv run scripts/build_epub.py --verbose # Custom output location uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub # Limit concurrent requests (if rate-limited) uv run scripts/build_epub.py --max-concurrent 5 ``` ## Output Creates `claude-howto-guide.epub` in the repository root directory. The EPUB includes: - Cover image with project logo - Table of contents with nested sections - All markdown content converted to EPUB-compatible HTML - Mermaid diagrams rendered as PNG images ## Running Tests ```bash # With virtual environment source .venv/bin/activate pytest scripts/tests/ -v # Or with uv directly uv run --with pytest --with pytest-asyncio \ --with ebooklib --with markdown --with beautifulsoup4 \ --with httpx --with pillow --with tenacity \ pytest scripts/tests/ -v ``` ## Dependencies Managed via PEP 723 inline script metadata: | Package | Purpose | |---------|---------| | `ebooklib` | EPUB generation | | `markdown` | Markdown to HTML conversion | | `beautifulsoup4` | HTML parsing | | `httpx` | Async HTTP client | | `pillow` | Cover image generation | | `tenacity` | Retry logic | ## Troubleshooting **Build fails with network error**: Check internet connectivity and Kroki.io status. Try `--timeout 60`. **Rate limiting**: Reduce concurrent requests with `--max-concurrent 3`. **Missing logo**: The script generates a text-only cover if `claude-howto-logo.png` is not found.