# バッチ設計書 11-CI-docs.yml

## 概要

本ドキュメントは、libuvプロジェクトのSphinxドキュメント生成および外部リンク検証を行うCI/CDワークフロー「CI-docs.yml」のバッチ設計書である。GitHub Actionsによりプルリクエスト時に自動実行され、ドキュメントの品質を担保する。

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

CI-docs.ymlは、libuvプロジェクトのドキュメントディレクトリ配下のファイルが変更されたプルリクエストに対して、Sphinxによるhtml生成とリンクチェックを自動実行するCI/CDワークフローである。

**業務上の目的・背景**：libuvのAPIドキュメントはSphinxで管理されており、ドキュメントの変更がビルド可能であること、および外部リンクが壊れていないことを継続的に検証する必要がある。手動でのチェックは漏れが発生しやすいため、CI/CDパイプラインに組み込むことで品質を自動的に担保する。

**バッチの実行タイミング**：プルリクエスト作成時および更新時に自動実行される。対象は `docs/**` 配下のファイル変更（ただし `docs/code/**` は除外）および `.github/workflows/CI-docs.yml` 自体の変更。

**主要な処理内容**：
1. Ubuntu最新環境のセットアップとリポジトリのチェックアウト
2. Python 3.9環境のセットアップ（pip依存パッケージのキャッシュ有効）
3. `docs/requirements.txt` に基づくSphinx関連パッケージのインストール
4. `make -C docs html` によるHTMLドキュメントのビルド
5. `make -C docs linkcheck` による外部リンクの整合性検証

**前後の処理との関連**：本ワークフローは独立して実行される。前提として `docs/Makefile`（No.12）、`docs/src/conf.py`（No.13）、`docs/src/sphinx-plugins/manpage.py`（No.14）が正しく構成されている必要がある。後続処理としてReadTheDocs（No.22）での本番ドキュメント公開がある。

**影響範囲**：プルリクエストのマージ可否判断に影響する。ドキュメントビルドの失敗やリンク切れがある場合、マージがブロックされる。

## バッチ種別

CI/CD自動検証（ドキュメントビルド・リンクチェック）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | プルリクエストごと（随時） |
| 実行時刻 | プルリクエスト作成・更新時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actionsイベント（pull_request） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| 対象パス変更 | `docs/**`（`docs/code/**` を除く）または `.github/workflows/CI-docs.yml` に変更があること |
| GitHub Actions有効 | リポジトリでGitHub Actionsが有効化されていること |
| ネットワーク接続 | pip依存パッケージダウンロードおよびリンクチェックのため外部ネットワーク接続が可能であること |

### 実行可否判定

プルリクエストの差分ファイルが `on.pull_request.paths` に指定されたパスパターンに一致する場合のみ実行される。`docs/code/**` はサンプルコードビルド専用CI（CI-sample.yml）で別途検証されるため除外される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| python-version | string | Yes | 3.9 | Python実行環境のバージョン |
| cache | string | Yes | pip | pipキャッシュの有効化 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| docs/requirements.txt | テキスト（pip requirements形式） | Sphinx関連パッケージ依存定義（furo==2024.8.6, Sphinx==7.0.1等） |
| docs/src/ 配下のrstファイル群 | reStructuredText | Sphinxドキュメントソースファイル |
| docs/src/conf.py | Python | Sphinx設定ファイル |
| docs/src/sphinx-plugins/manpage.py | Python | カスタムSphinxロールプラグイン |
| include/uv/version.h | C言語ヘッダ | バージョン情報取得元（conf.pyから参照） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| docs/build/html/ | HTMLファイル群 | Sphinxが生成したHTMLドキュメント |
| docs/build/doctrees/ | pickleファイル群 | Sphinxドキュメントツリーキャッシュ |
| docs/build/linkcheck/output.txt | テキスト | リンクチェック結果レポート |
| GitHub Actions ログ | テキスト | ビルドログおよびリンクチェック結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | index.html（ルート）およびサブページ群 |
| 出力先 | docs/build/html/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（HTML形式） |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v6 によるソースコード取得
2. Python環境セットアップ
   └─ actions/setup-python@v6 でPython 3.9をインストール、pipキャッシュを有効化
3. 依存パッケージインストール
   └─ pip install -r docs/requirements.txt でSphinx・furo等をインストール
4. HTMLドキュメントビルド
   └─ make -C docs html（sphinx-build -b html src build/html）
5. リンクチェック実行
   └─ make -C docs linkcheck（sphinx-build -b linkcheck src build/linkcheck）
```

### フローチャート

```mermaid
flowchart TD
    A[PR作成/更新] --> B{対象パス変更あり?}
    B -->|Yes| C[リポジトリチェックアウト]
    B -->|No| Z[スキップ]
    C --> D[Python 3.9セットアップ]
    D --> E[pip install requirements.txt]
    E --> F[make html]
    F --> G{ビルド成功?}
    G -->|Yes| H[make linkcheck]
    G -->|No| X[失敗: ビルドエラー]
    H --> I{リンクチェック成功?}
    I -->|Yes| J[CI成功]
    I -->|No| Y[失敗: リンク切れ検出]
    X --> K[GitHub Actions失敗ステータス]
    Y --> K
    J --> L[GitHub Actions成功ステータス]
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exit 1 | ビルドエラー | rstファイルの構文エラー、conf.pyの設定不備 | エラーログを確認しrstファイルまたはconf.pyを修正 |
| exit 1 | リンクチェックエラー | 外部リンクが404、タイムアウト等 | リンク先URLを更新または削除 |
| exit 1 | 依存パッケージエラー | requirements.txtのパッケージがPyPIから取得不可 | パッケージバージョンを確認し更新 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（GitHub Actionsの標準動作として自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし（手動再実行は可能） |

### 障害時対応

1. GitHub Actionsのログから失敗ステップを特定する
2. htmlビルド失敗の場合：rstファイルの構文エラーやconf.pyの設定不備を修正する
3. linkcheck失敗の場合：output.txtを確認し、壊れたリンクを修正する
4. 修正をコミットしプルリクエストを更新すると自動再実行される

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ドキュメントページ数に依存（数十〜数百ページ） |
| 目標処理時間 | 5分以内（htmlビルド + linkcheck） |
| メモリ使用量上限 | GitHub Actions標準ランナーのメモリ制限（7GB） |

## 排他制御

同一プルリクエストに対する複数回の実行はGitHub Actionsの標準動作として最新のコミットのみが有効となる（自動キャンセル設定は明示的に定義されていないため、並列実行される可能性がある）。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsジョブ開始情報 |
| 進捗ログ | 各ステップ実行時 | pip install出力、sphinx-build出力 |
| 終了ログ | ワークフロー終了時 | ジョブの成功/失敗ステータス |
| エラーログ | エラー発生時 | Sphinxビルドエラー詳細、リンクチェック結果 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行結果 | 失敗時 | プルリクエストのステータスチェック |
| 実行時間 | GitHub Actions標準タイムアウト（6時間） | GitHub Actions通知 |

## 備考

- Python 3.9が指定されているのはSphinxおよびfuroテーマの互換性のためである
- pipキャッシュが有効化されており、依存パッケージの再ダウンロードを回避して実行時間を短縮している
- `docs/code/**` パスは意図的に除外されており、サンプルコードのビルドはCI-sample.yml（No.10）が担当する
