# バッチ設計書 12-docs/Makefile

## 概要

本ドキュメントは、libuvプロジェクトのSphinxドキュメント生成を制御するMakefile（`docs/Makefile`）のバッチ設計書である。複数の出力形式（HTML、PDF、man、epub等）のドキュメントビルドおよびリンクチェック・doctest等の検証機能を提供する。

### 本バッチの処理概要

docs/Makefileは、Sphinxドキュメントビルドシステムのフロントエンドとして機能し、sphinx-buildコマンドを各種出力形式に対応するオプション付きで実行するMakefileである。

**業務上の目的・背景**：libuvはC言語で記述されたクロスプラットフォーム非同期I/Oライブラリであり、開発者向けのAPIドキュメントが不可欠である。Sphinxを使用してreStructuredText形式のソースからHTML、PDF、man page、epub等の多様な形式でドキュメントを生成する必要がある。本Makefileは、これらのビルドターゲットを統一的なインタフェースで提供し、開発者やCIシステムが簡単にドキュメントを生成・検証できるようにする。

**バッチの実行タイミング**：開発者によるローカルでの手動実行（随時）、およびCI/CDワークフロー（CI-docs.yml: No.11）からの自動実行。

**主要な処理内容**：
1. sphinx-buildコマンドによるHTMLドキュメント生成（`make html`）
2. ライブリロード対応のHTML生成（`make livehtml` - sphinx-autobuild使用）
3. 単一HTMLファイル生成（`make singlehtml`）
4. LaTeX/PDF出力（`make latexpdf`）
5. manページ生成（`make man`）
6. epub電子書籍生成（`make epub`）
7. 外部リンク整合性チェック（`make linkcheck`）
8. doctest実行（`make doctest`）
9. 各種シリアライズ形式出力（pickle, json, xml等）
10. クリーンビルド（`make clean`）

**前後の処理との関連**：本Makefileは `docs/src/conf.py`（No.13）を設定ファイルとして使用し、`docs/src/sphinx-plugins/manpage.py`（No.14）をカスタムプラグインとして読み込む。CI-docs.yml（No.11）およびReadTheDocs（No.22）から呼び出される。

**影響範囲**：`docs/build/` ディレクトリ配下に各種形式のドキュメントを生成する。`make clean` 実行時は `docs/build/` 配下の全ファイルが削除される。

## バッチ種別

ドキュメント生成（ビルドスクリプト）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動）/ プルリクエストごと（CI） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（make コマンド）/ CI（CI-docs.yml） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| sphinx-build | sphinx-buildコマンドがPATH上に存在すること（未検出時はエラーメッセージを表示） |
| Sphinx関連パッケージ | docs/requirements.txt記載のパッケージがインストール済みであること |
| ソースファイル | docs/src/ 配下にrstファイル群が存在すること |
| conf.py | docs/src/conf.py が正しく設定されていること |

### 実行可否判定

sphinx-buildコマンドの存在チェックを `which` コマンドで実行する。コマンドが見つからない場合は `$(error ...)` でMakeの実行を中断し、インストール方法を案内するエラーメッセージを出力する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| SPHINXOPTS | string | No | （空） | sphinx-buildに渡す追加オプション |
| SPHINXBUILD | string | No | sphinx-build | sphinx-buildコマンドパス |
| SPHINXAUTOBUILD | string | No | sphinx-autobuild | sphinx-autobuildコマンドパス |
| PAPER | string | No | （空） | 用紙サイズ（a4 / letter） |
| BUILDDIR | string | No | build | ビルド出力先ディレクトリ |
| SRCDIR | string | No | src | ソースディレクトリ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| docs/src/*.rst | reStructuredText | Sphinxドキュメントソース |
| docs/src/conf.py | Python | Sphinx設定ファイル |
| docs/src/sphinx-plugins/ | Python | カスタムSphinxプラグイン |
| docs/src/static/ | 画像・CSS等 | 静的アセットファイル |
| docs/src/templates/ | Jinja2テンプレート | HTMLテンプレートカスタマイズ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| build/html/ | HTMLファイル群 | スタンドアロンHTMLドキュメント |
| build/dirhtml/ | HTMLファイル群 | ディレクトリ構造HTMLドキュメント |
| build/singlehtml/ | 単一HTMLファイル | 単一ページHTMLドキュメント |
| build/latex/ | LaTeXファイル群 | LaTeX/PDFドキュメント |
| build/man/ | manページ | UNIXマニュアルページ |
| build/epub/ | epubファイル | 電子書籍形式 |
| build/text/ | テキストファイル | プレーンテキスト形式 |
| build/json/ | JSONファイル群 | JSON形式 |
| build/pickle/ | pickleファイル群 | Pythonシリアライズ形式 |
| build/xml/ | XMLファイル群 | Docutils XML形式 |
| build/linkcheck/output.txt | テキスト | リンクチェック結果 |
| build/doctest/output.txt | テキスト | doctestテスト結果 |
| build/doctrees/ | pickleファイル群 | ドキュメントツリーキャッシュ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各ターゲットに応じた命名規則 |
| 出力先 | docs/build/{ターゲット名}/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. Make実行（ターゲット指定）
   └─ 例: make html
2. sphinx-build存在チェック
   └─ which sphinx-build が失敗した場合はエラー終了
3. 内部変数構成
   └─ ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT) $(SPHINXOPTS) src
4. sphinx-build実行
   └─ sphinx-build -b {ターゲット} $(ALLSPHINXOPTS) build/{ターゲット}
5. 完了メッセージ出力
   └─ "Build finished." メッセージ
```

### フローチャート

```mermaid
flowchart TD
    A[make ターゲット] --> B{sphinx-build存在?}
    B -->|No| C[エラー終了: インストール案内]
    B -->|Yes| D[内部変数構成]
    D --> E{ターゲット判定}
    E -->|html| F[sphinx-build -b html]
    E -->|livehtml| G[make html + sphinx-autobuild]
    E -->|latexpdf| H[sphinx-build -b latex + make all-pdf]
    E -->|linkcheck| I[sphinx-build -b linkcheck]
    E -->|clean| J[rm -rf build/*]
    E -->|その他| K[sphinx-build -b ターゲット]
    F --> L[完了メッセージ]
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | - |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Makeエラー | 前提条件エラー | sphinx-buildコマンドが未インストール | Sphinxをインストールする |
| exit 1 | ビルドエラー | rstファイルの構文エラー | sphinx-buildのエラー出力を確認し修正 |
| exit 1 | リンクチェックエラー | 外部リンクが無効 | linkcheck出力を確認しリンクを修正 |
| exit 1 | LaTeXエラー | pdflatexの実行失敗 | LaTeX環境の整備とエラー修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（手動再実行） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. sphinx-build未検出：`pip install sphinx` でSphinxをインストールする
2. ビルドエラー：エラー出力のファイル名・行番号を確認してrstファイルを修正する
3. リンクチェックエラー：`build/linkcheck/output.txt` を確認して壊れたリンクを修正する
4. `make clean` を実行してキャッシュをクリアし再ビルドする

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ファイルシステムベースの処理） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（make clean で出力をクリア可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ドキュメントページ数に依存 |
| 目標処理時間 | 数分以内（htmlビルド） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同一のBUILDDIRに対する同時ビルドは想定されていない。`make clean` と他のターゲットの同時実行は避ける必要がある。doctreesキャッシュの共有により、異なるターゲット間でのビルド結果が再利用される（i18nビルダーは例外として独立した環境を使用する）。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 暗黙的 | Makeターゲット実行開始 |
| 進捗ログ | sphinx-build実行中 | Sphinxのビルド進捗メッセージ |
| 終了ログ | ビルド完了時 | "Build finished." および出力先パス |
| エラーログ | エラー発生時 | Sphinxエラーメッセージ、ファイル名・行番号 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド結果 | 失敗時 | CI/CDワークフロー（CI-docs.yml）のステータス |
| リンクチェック結果 | 壊れたリンク検出時 | linkcheck出力ファイル |

## 備考

- 本Makefileはsphinx-quickstartにより自動生成されたものをベースとしている
- `livehtml` ターゲットはsphinx-autobuildによるライブリロード機能を提供し、ドキュメント執筆時の確認作業を効率化する
- 用紙サイズは `PAPER` 変数で `a4` または `letter` を指定可能（LaTeX出力時に使用）
- `latexpdfja` ターゲットは日本語PDF出力用（platex + dvipdfmx）に対応している
- i18nビルダーは他のビルダーと環境・doctreesを共有できないため、`I18NSPHINXOPTS` 変数で独立したオプションが定義されている
