# バッチ設計書 13-conf.py

## 概要

本ドキュメントは、libuvプロジェクトのSphinx設定ファイル（`docs/src/conf.py`）のバッチ設計書である。Sphinxドキュメントビルド時の前処理として実行され、バージョン情報の自動取得、プラグイン設定、HTML/LaTeX/epub等の各種出力形式のメタデータ定義を行う。

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

conf.pyは、Sphinxドキュメントビルドエンジン（sphinx-build）が実行時に `execfile()` で読み込む設定ファイルである。libuvのバージョン情報をCヘッダファイルから動的に取得し、各種出力形式の設定を定義する。

**業務上の目的・背景**：libuvのAPIドキュメントは頻繁にバージョンアップが行われるため、バージョン番号をソースコードと同期させる仕組みが必要である。conf.pyは `include/uv/version.h` からメジャー・マイナー・パッチバージョンを正規表現で抽出することにより、ドキュメントとライブラリ本体のバージョン不整合を防止する。また、HTMLテーマ（furo）、カスタムプラグイン（manpage）、出力メタデータの一元管理を行う。

**バッチの実行タイミング**：sphinx-buildコマンド実行時に自動的に読み込まれる。直接実行されるスクリプトではなく、Sphinxビルドプロセスの設定ファイルとして機能する。

**主要な処理内容**：
1. `include/uv/version.h` からUV_VERSION_MAJOR/MINOR/PATCH/IS_RELEASE/SUFFIXを正規表現で抽出
2. バージョン文字列の構築（リリース版は `X.Y.Z`、開発版は `X.Y.Z-suffix`）
3. カスタムSphinxプラグイン（manpage）のパス追加と登録
4. HTML出力設定（furoテーマ、ロゴ、ファビコン、静的アセット）
5. LaTeX出力設定（ドキュメント構造、著者情報）
6. manページ出力設定
7. epub出力設定（Dublin Core メタデータ）
8. Texinfo出力設定

**前後の処理との関連**：本ファイルは `docs/Makefile`（No.12）を通じてsphinx-buildから読み込まれる。`docs/src/sphinx-plugins/manpage.py`（No.14）をカスタム拡張として使用する。`include/uv/version.h` を入力として参照する。CI-docs.yml（No.11）による自動検証の対象でもある。

**影響範囲**：Sphinxが生成する全ドキュメント（HTML、PDF、man、epub等）のメタデータ、テーマ、バージョン表記に影響する。

## バッチ種別

ドキュメント生成前処理（設定・メタデータ定義）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | sphinx-buildの実行ごと |
| 実行時刻 | sphinx-build実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | sphinx-buildによる自動読み込み |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| include/uv/version.h | バージョン情報ヘッダファイルが存在し、UV_VERSION_MAJOR/MINOR/PATCH/IS_RELEASE/SUFFIXマクロが定義されていること |
| sphinx-pluginsディレクトリ | docs/src/sphinx-plugins/ 配下にmanpage.pyが存在すること |
| 静的アセット | docs/src/static/ 配下にlogo.png、favicon.icoが存在すること |
| Python環境 | os, re, sys モジュールが利用可能であること |

### 実行可否判定

sphinx-buildプロセスがconf.pyをexecfile()で読み込む際に自動的に実行される。`get_libuv_version()` 関数で `include/uv/version.h` の読み込みに失敗した場合は例外をキャッチし、バージョン文字列として `'unknown'` を返す（ビルドは継続する）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| 該当なし | - | - | - | conf.pyは外部パラメータを受け取らない（全設定をファイル内で定義） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| include/uv/version.h | C言語ヘッダ | UV_VERSION_MAJOR/MINOR/PATCH/IS_RELEASE/SUFFIXマクロ定義 |
| docs/src/sphinx-plugins/manpage.py | Python | カスタムSphinxロールプラグイン |
| docs/src/static/logo.png | PNG画像 | ドキュメントサイドバーロゴ |
| docs/src/static/favicon.ico | ICO画像 | ブラウザファビコン |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Sphinxビルド設定 | Python変数群 | sphinx-buildが参照する設定値 |

conf.pyは直接ファイル出力を行わない。Sphinxエンジンに設定値を提供し、Sphinxが各種形式のドキュメントを生成する。

### 出力ファイル仕様

conf.pyの設定により間接的に以下の出力が制御される：

| 項目 | 内容 |
|-----|------|
| HTMLタイトル | 'libuv documentation' |
| HTMLショートタイトル | 'libuv {version} documentation' |
| HTMLテーマ | furo |
| LaTeX出力ファイル | libuv.tex |
| manページセクション | 1 |
| epub識別名 | libuv |

## 処理フロー

### 処理シーケンス

```
1. get_libuv_version() 関数定義
   └─ ../../include/uv/version.h を相対パスで開く
2. バージョン情報抽出
   └─ UV_VERSION_MAJOR, MINOR, PATCH を正規表現で抽出
   └─ UV_VERSION_IS_RELEASE, UV_VERSION_SUFFIX を抽出
3. バージョン文字列構築
   └─ IS_RELEASE=1 の場合: "X.Y.Z"
   └─ IS_RELEASE=0 の場合: "X.Y.Z-suffix"
4. sys.pathにsphinx-pluginsを追加
   └─ sys.path.insert(0, os.path.abspath('sphinx-plugins'))
5. Sphinx拡張の登録
   └─ extensions = ['manpage']
6. 汎用設定
   └─ project, copyright, version, release, master_doc 等
7. HTML出力設定
   └─ html_theme, html_title, html_logo, html_favicon 等
8. LaTeX出力設定
   └─ latex_documents, latex_elements
9. manページ出力設定
   └─ man_pages
10. Texinfo出力設定
    └─ texinfo_documents
11. epub出力設定
    └─ epub_title, epub_author, epub_publisher 等
```

### フローチャート

```mermaid
flowchart TD
    A[sphinx-buildがconf.pyを読み込み] --> B[get_libuv_version実行]
    B --> C{version.h読み込み成功?}
    C -->|Yes| D[正規表現でバージョン抽出]
    C -->|No| E[バージョン = 'unknown']
    D --> F{IS_RELEASE?}
    F -->|1| G[バージョン文字列: X.Y.Z]
    F -->|0| H[バージョン文字列: X.Y.Z-suffix]
    G --> I[設定変数群の定義]
    H --> I
    E --> I
    I --> J[sphinx-pluginsパス追加]
    J --> K[拡張機能登録: manpage]
    K --> L[HTML/LaTeX/man/epub設定]
    L --> M[Sphinxビルドエンジンに設定値を提供]
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Exception | ファイル読み込みエラー | include/uv/version.hが存在しないまたは読み込み不可 | バージョンを'unknown'に設定しビルド継続 |
| Exception | 正規表現マッチ失敗 | version.hの形式がマクロ定義パターンに一致しない | バージョンを'unknown'に設定しビルド継続 |
| ImportError | プラグイン読み込みエラー | manpage.pyが存在しないまたは構文エラー | sphinx-pluginsディレクトリを確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回 |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. バージョン取得失敗時：`get_libuv_version()` がtry-exceptで例外をキャッチし `'unknown'` を返すため、ビルドは継続される。version.hのパスまたはマクロ定義を確認する。
2. プラグイン読み込み失敗時：`docs/src/sphinx-plugins/manpage.py` の存在と内容を確認する。
3. テーマ関連エラー時：furoテーマがインストールされているか `pip list | grep furo` で確認する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回のconf.py読み込み（version.h 1ファイル読み込み） |
| 目標処理時間 | 即時（ミリ秒単位） |
| メモリ使用量上限 | 無視できる程度 |

## 排他制御

conf.pyは読み取り専用のファイルであり、排他制御は不要。ただし、version.hへの書き込みとsphinx-buildの同時実行は避けることが望ましい。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 該当なし | conf.py自体はログを出力しない |
| 進捗ログ | 該当なし | conf.py自体はログを出力しない |
| 終了ログ | 該当なし | conf.py自体はログを出力しない |
| エラーログ | バージョン取得失敗時 | 暗黙的にバージョンが'unknown'となる（明示的なログ出力なし） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ドキュメントバージョン | 'unknown'の場合 | Sphinxビルド出力を目視確認 |

## 備考

- conf.pyは `sphinx-quickstart` により自動生成されたものをベースに、libuvプロジェクト固有のカスタマイズが追加されている
- バージョン取得は `../../include/uv/version.h` への相対パスで行われるため、conf.pyの実行時カレントディレクトリが `docs/src/` であることが前提となる
- 現在のバージョンは `1.52.1-dev`（UV_VERSION_IS_RELEASE=0のため`-dev`サフィックス付き）
- HTMLテーマ `furo` はモダンなレスポンシブデザインのSphinxテーマであり、docs/requirements.txtにバージョン固定（furo==2024.8.6）で定義されている
- `pygments_style = 'sphinx'` によりシンタックスハイライトスタイルが設定されている
- epub設定にはDublin Core準拠のメタデータ（title, author, publisher, copyright）が定義されている
