# バッチ設計書 22-.readthedocs.yaml

## 概要

本ドキュメントは、libuvプロジェクトのReadTheDocs向け自動ドキュメントビルド設定ファイル `.readthedocs.yaml` のバッチ設計書である。このファイルはReadTheDocs（RTD）プラットフォーム上でlibuvのAPIドキュメントを自動的にビルド・公開するための設定を定義する。

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

`.readthedocs.yaml` は、ReadTheDocs（https://readthedocs.org/）プラットフォームがlibuvリポジトリの変更を検知した際に、Sphinxドキュメントを自動的にビルドしてホスティングするための設定ファイルである。RTDはGitHubリポジトリにWebhookを設定し、pushイベントを受信すると本設定ファイルに基づいてビルド環境を構築し、ドキュメントを生成・公開する。

**業務上の目的・背景**：libuvはC言語で記述された非同期I/Oライブラリであり、APIドキュメントは開発者がライブラリを正しく使用するために不可欠である。ReadTheDocsを利用することで、ドキュメントのビルド・公開を完全に自動化し、ソースコードとドキュメントの同期を維持できる。手動でのドキュメントビルド・デプロイの手間を排除し、常に最新のAPIドキュメントをhttps://docs.libuv.org/ 等で公開することが目的である。

**バッチの実行タイミング**：GitHubリポジトリへのpush発生時（Webhookトリガー）。ブランチやタグへのpushに応じて、対応するバージョンのドキュメントが自動的にビルド・公開される。

**主要な処理内容**：
1. ReadTheDocsプラットフォームがGitHub Webhookを受信し、ビルドをトリガーする
2. Ubuntu 22.04ベースのビルド環境を構築する
3. Python 3.9をインストールし、`docs/requirements.txt` の依存パッケージ（Sphinx 7.0.1、furo 2024.8.6等）をpipでインストールする
4. Sphinxビルダー（html）を使用して `docs/src/conf.py` を設定ファイルとしてドキュメントをビルドする
5. ビルド成果物をReadTheDocsのホスティング基盤にデプロイする

**前後の処理との関連**：本設定は `docs/src/conf.py`（No.13）のSphinx設定に依存し、`docs/Makefile`（No.12）と同じSphinxビルドプロセスをRTDプラットフォーム上で実行する。CI-docs.yml（No.11）はGitHub Actions上での同等のドキュメントビルド検証であり、RTDでのビルドとは独立して動作する。

**影響範囲**：ReadTheDocs上でホスティングされるlibuvのAPIドキュメント（HTML形式）。全てのバージョンのドキュメント公開状態に影響する。

## バッチ種別

ドキュメント生成 / 自動デプロイ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（GitHubリポジトリへのpush発生時） |
| 実行時刻 | push発生後即時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Webhook（pushイベント） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ReadTheDocsプロジェクト設定 | RTD上でlibuvプロジェクトが登録され、GitHubリポジトリと連携していること |
| GitHub Webhook設定 | リポジトリにRTD用のWebhookが設定されていること |
| `.readthedocs.yaml` の存在 | リポジトリルートに設定ファイルが存在すること（version: 2形式） |
| `docs/requirements.txt` の存在 | Python依存パッケージの定義ファイルが存在すること |
| `docs/src/conf.py` の存在 | Sphinx設定ファイルが存在すること |

### 実行可否判定

ReadTheDocsは `.readthedocs.yaml` の `version: 2` を確認し、v2形式の設定として解釈する。設定ファイルが存在しないか、形式が不正な場合はビルドが失敗する。`fail_on_warning: false` が設定されているため、Sphinxの警告（リンク切れ等）があってもビルドは成功として扱われる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| version | integer | Yes | - | ReadTheDocs設定ファイルのバージョン（`2` を指定） |
| sphinx.builder | string | Yes | - | Sphinxビルダーの種類（`html` を指定） |
| sphinx.configuration | string | Yes | - | Sphinx設定ファイルのパス（`docs/src/conf.py`） |
| sphinx.fail_on_warning | boolean | No | true | 警告時にビルドを失敗させるか（`false` を指定） |
| build.os | string | Yes | - | ビルド環境のOS（`ubuntu-22.04`） |
| build.tools.python | string | Yes | - | Pythonバージョン（`3.9`） |
| python.install[].requirements | string | No | - | pip依存パッケージファイルのパス（`docs/requirements.txt`） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| `.readthedocs.yaml` | YAML | RTDビルド設定ファイル（本バッチの定義本体） |
| `docs/requirements.txt` | テキスト | Python依存パッケージ一覧（Sphinx 7.0.1、furo 2024.8.6等、全29パッケージ） |
| `docs/src/conf.py` | Python | Sphinx設定ファイル（バージョン自動取得、テーマ設定、拡張機能設定等） |
| `docs/src/*.rst` | reStructuredText | ドキュメントソースファイル（約42ファイル） |
| `docs/src/sphinx-plugins/manpage.py` | Python | Sphinxカスタムプラグイン（man参照リンク生成） |
| `include/uv/version.h` | Cヘッダ | libuvバージョン情報（conf.pyが参照） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ReadTheDocsホスティング | HTML | ビルドされたAPIドキュメント（furoテーマ適用） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | HTMLファイル群（index.html等） |
| 出力先 | ReadTheDocsホスティング基盤（https://docs.libuv.org/ 等） |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（HTML） |

## 処理フロー

### 処理シーケンス

```
1. GitHub Webhookトリガー受信
   └─ RTDがpushイベントを検知

2. ビルド環境構築
   ├─ Ubuntu 22.04ベースのコンテナ起動
   └─ Python 3.9のインストール

3. 依存パッケージインストール
   └─ pip install -r docs/requirements.txt
      ├─ Sphinx 7.0.1
      ├─ furo 2024.8.6（HTMLテーマ）
      └─ その他依存パッケージ（27個）

4. Sphinxビルド実行
   ├─ 設定ファイル: docs/src/conf.py
   ├─ ビルダー: html
   ├─ バージョン自動取得: include/uv/version.h から
   └─ カスタムプラグイン: manpage.py の読み込み

5. ビルド結果の検証
   └─ fail_on_warning: false のため、警告は無視

6. デプロイ
   └─ ビルド成果物をRTDホスティング基盤に公開
```

### フローチャート

```mermaid
flowchart TD
    A[GitHub push発生] --> B[ReadTheDocs Webhook受信]
    B --> C[Ubuntu 22.04 環境構築]
    C --> D[Python 3.9 インストール]
    D --> E[pip install -r docs/requirements.txt]
    E --> F[Sphinxビルド実行]
    F --> G{ビルド成功?}
    G -->|Yes| H[RTDにデプロイ]
    G -->|No| I[ビルドエラー通知]
    H --> J[ドキュメント公開完了]
    I --> K[ビルド終了 - 失敗]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | 本バッチはドキュメントビルド・デプロイ処理であり、データベース操作は行わない |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BUILD_FAILED | 依存パッケージエラー | `docs/requirements.txt` のパッケージインストールに失敗した場合 | requirements.txtのバージョン指定を確認し、互換性のあるバージョンに更新する |
| BUILD_FAILED | Sphinx設定エラー | `docs/src/conf.py` に構文エラーがある場合 | conf.pyの構文を修正する |
| BUILD_FAILED | reStructuredTextエラー | .rstファイルのマークアップに致命的なエラーがある場合 | 該当するrstファイルの構文を修正する |
| BUILD_FAILED | バージョン取得失敗 | `include/uv/version.h` が存在しないか形式が不正な場合 | version.hの存在と内容を確認する |
| N/A | Sphinx警告 | リンク切れ、参照不明等の警告 | `fail_on_warning: false` のため無視される（ビルドは成功） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | RTDプラットフォーム側で自動管理（手動リビルド可能） |
| リトライ間隔 | RTDプラットフォーム側で管理 |
| リトライ対象エラー | 一時的なネットワークエラー、パッケージダウンロードタイムアウト |

### 障害時対応

ビルドが失敗した場合の対応手順：
1. ReadTheDocsのビルドログを確認し、失敗原因を特定する
2. `docs/requirements.txt` の依存パッケージのバージョン互換性を確認する
3. ローカル環境で `cd docs && make html` を実行し、同様のエラーが再現するか確認する
4. 修正後、pushすることで自動的にリビルドが実行される
5. 必要に応じてRTD管理画面から手動でビルドを再実行する

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ドキュメントビルド処理） |
| コミットタイミング | 該当なし |
| ロールバック条件 | ビルド失敗時、前回成功時のドキュメントがそのまま公開され続ける |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | rstファイル約42個のHTML変換 |
| 目標処理時間 | 数分以内（RTDプラットフォームの標準的なビルド時間） |
| メモリ使用量上限 | RTDプラットフォーム側の制約に依存 |

## 排他制御

ReadTheDocsプラットフォームが同一プロジェクトのビルドキューを管理する。同時に複数のpushが発生した場合、ビルドはキューイングされ順次実行される。最新のpushに対するビルドが最終的な公開ドキュメントとなる。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルドログ | ビルド全体 | RTD管理画面で確認可能なSphinxビルドログ |
| 依存解決ログ | パッケージインストール時 | pip installの出力 |
| エラーログ | ビルド失敗時 | Sphinxのエラーメッセージ、Python例外トレース |
| 警告ログ | ビルド中 | Sphinxの警告メッセージ（`fail_on_warning: false` のため無視） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルドステータス | ビルド失敗 | ReadTheDocs管理画面、メール通知（RTD設定に依存） |
| ビルド時間 | RTDプラットフォームのタイムアウト | ReadTheDocs管理画面 |

## 備考

- `.readthedocs.yaml` はReadTheDocs v2設定形式を使用している。v1形式は非推奨となっている
- HTMLテーマとして `furo` が使用されている（`docs/src/conf.py` の `html_theme = 'furo'`）
- `docs/requirements.txt` にはSphinx本体とその依存パッケージ、furoテーマが全てバージョン固定で定義されており、ビルドの再現性が確保されている
- `conf.py` はlibuvのバージョンを `include/uv/version.h` から動的に取得するため、ドキュメントのバージョン表示は常にソースコードと同期する
- カスタムSphinxプラグイン `manpage.py`（No.14）がman参照リンクの生成に使用される
- CI-docs.yml（No.11）はGitHub Actions上で同等のSphinxビルドとリンクチェックを実行しており、RTDでのビルド失敗を事前に検出する補完的な役割を持つ
