1d1df9235b
- Translate all 101 markdown files: P1 core, all 10 modules, examples, auxiliary docs (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CLAUDE.md, etc.), peripheral docs (.github/, docs/, resources/, scripts/) - Translate comments and user-facing messages in 06-hooks/*.sh examples - Copy 05-mcp/*.json examples (standard JSON, no comments) - Update root README.md language switcher to include 日本語 - Add ja/TRANSLATION_NOTES.md (glossary + style guide) All translations pass pre-commit quality gates (markdown-lint, cross-references, mermaid-syntax, link-check, build-epub).
124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
<!-- i18n-source: scripts/README.md -->
|
||
<!-- i18n-source-sha: 58e586f -->
|
||
<!-- i18n-date: 2026-04-27 -->
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
|
||
<img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
|
||
</picture>
|
||
|
||
# EPUB ビルダースクリプト
|
||
|
||
Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍をビルドするスクリプト。
|
||
|
||
## 特徴
|
||
|
||
- フォルダ構成（01-slash-commands、02-memory など）に沿って章を整理する
|
||
- Mermaid 図を Kroki.io API 経由で PNG 画像としてレンダリングする
|
||
- 非同期並行取得 — すべての図を並列にレンダリングする
|
||
- プロジェクトロゴから表紙画像を生成する
|
||
- 内部 Markdown リンクを EPUB の章参照へ変換する
|
||
- 厳格モード — レンダリング不能な図があればビルドを失敗させる
|
||
|
||
## 必要環境
|
||
|
||
- Python 3.10+
|
||
- [uv](https://github.com/astral-sh/uv)
|
||
- Mermaid 図レンダリング用のインターネット接続
|
||
|
||
## クイックスタート
|
||
|
||
```bash
|
||
# 最も簡単な方法 — uv がすべてを処理する
|
||
uv run scripts/build_epub.py
|
||
```
|
||
|
||
## 開発環境セットアップ
|
||
|
||
```bash
|
||
# 仮想環境を作成
|
||
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)
|
||
```
|
||
|
||
## 使用例
|
||
|
||
```bash
|
||
# 詳細ログ付きでビルド
|
||
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 図
|
||
|
||
## テストの実行
|
||
|
||
```bash
|
||
# 仮想環境を使う場合
|
||
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 のインラインスクリプトメタデータで管理する：
|
||
|
||
| パッケージ | 用途 |
|
||
|---------|---------|
|
||
| `ebooklib` | EPUB 生成 |
|
||
| `markdown` | Markdown から HTML への変換 |
|
||
| `beautifulsoup4` | HTML パース |
|
||
| `httpx` | 非同期 HTTP クライアント |
|
||
| `pillow` | 表紙画像生成 |
|
||
| `tenacity` | リトライ処理 |
|
||
|
||
## トラブルシューティング
|
||
|
||
**ネットワークエラーでビルドが失敗する**: インターネット接続と Kroki.io の稼働状況を確認する。`--timeout 60` を試す。
|
||
|
||
**レート制限**: `--max-concurrent 3` で並行リクエスト数を減らす。
|
||
|
||
**ロゴが見つからない**: `claude-howto-logo.png` が見つからない場合、スクリプトはテキストのみの表紙を生成する。
|