mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-05-09 22:07:32 +02:00
Luong NGUYEN
540508f392
- Add pre-commit hooks: Ruff lint/format, Bandit security scan, YAML/TOML validation - Add GitHub Actions CI workflow: lint, security, test, and build jobs - Configure Ruff and Bandit in pyproject.toml - Add pytest test suite for build_epub.py (25 tests) - Fix code issues: exception chaining, httpx timeout, formatting - Add requirements.txt and requirements-dev.txt
116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
# 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.
|