Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍をビルドするスクリプト。

特徴

• フォルダ構成（01-slash-commands、02-memory など）に沿って章を整理する
• Mermaid 図を Kroki.io API 経由で PNG 画像としてレンダリングする
• 非同期並行取得 — すべての図を並列にレンダリングする
• プロジェクトロゴから表紙画像を生成する
• 内部 Markdown リンクを EPUB の章参照へ変換する
• 厳格モード — レンダリング不能な図があればビルドを失敗させる

必要環境

• Python 3.10+
• uv
• Mermaid 図レンダリング用のインターネット接続

クイックスタート

# 最も簡単な方法 — uv がすべてを処理する
uv run scripts/build_epub.py

開発環境セットアップ

# 仮想環境を作成
uv venv

# 有効化して依存関係をインストール
source .venv/bin/activate
uv pip install -r requirements-dev.txt

# テストを実行
pytest scripts/tests/ -v

# スクリプトを実行
python scripts/build_epub.py

コマンドラインオプション

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)

使用例

# 詳細ログ付きでビルド
uv run scripts/build_epub.py --verbose

# 出力先をカスタマイズ
uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub

# 並行リクエスト数を制限（レート制限を受ける場合）
uv run scripts/build_epub.py --max-concurrent 5

出力

リポジトリのルートディレクトリに claude-howto-guide.epub を生成する。

EPUB には次が含まれる：

• プロジェクトロゴ付きの表紙画像
• ネストされた目次
• すべての Markdown コンテンツを EPUB 互換 HTML に変換したもの
• PNG 画像としてレンダリングされた Mermaid 図

テストの実行

# 仮想環境を使う場合
source .venv/bin/activate
pytest scripts/tests/ -v

# または uv で直接実行
uv run --with pytest --with pytest-asyncio \
    --with ebooklib --with markdown --with beautifulsoup4 \
    --with httpx --with pillow --with tenacity \
    pytest scripts/tests/ -v

依存関係

PEP 723 のインラインスクリプトメタデータで管理する：

トラブルシューティング

ネットワークエラーでビルドが失敗する: インターネット接続と Kroki.io の稼働状況を確認する。--timeout 60 を試す。

レート制限: --max-concurrent 3 で並行リクエスト数を減らす。

ロゴが見つからない: claude-howto-logo.png が見つからない場合、スクリプトはテキストのみの表紙を生成する。