# バッチ設計書 6-.github/workflows/ci_docs.yml

## 概要

本ドキュメントは、GitHub ActionsのドキュメントビルドCI設定ファイル `.github/workflows/ci_docs.yml` の設計仕様を定義するものである。

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

このバッチは、GitHub Actionsを使用してNimのドキュメント生成を自動的に実行するCI/CDワークフローである。コンパイラやドキュメント関連ファイルの変更時に、Linux/Windows/macOSの各プラットフォームでドキュメントをビルドし、develブランチへのプッシュ時にはGitHub Pagesへの公開も行う。

**業務上の目的・背景**：Nimプロジェクトのドキュメントは、コンパイラやライブラリの変更に伴って更新される必要がある。ドキュメント生成処理を自動化することで、変更の度に手動でドキュメントを生成・公開する手間を省き、常に最新のドキュメントをユーザーに提供できる。また、複数プラットフォームでのビルド検証により、ドキュメント生成処理のクロスプラットフォーム互換性を確保する。

**バッチの実行タイミング**：
- コンパイラソース（compiler/\*\*.nim）の変更時
- ドキュメントソース（doc/\*\*.rst, doc/\*\*.md）の変更時
- ライブラリソース（lib/\*\*.nim）の変更時
- ドキュメント関連ツール（tools/dochack/dochack.nim, tools/kochdocs.nim）の変更時
- その他ドキュメント関連設定ファイルの変更時

**主要な処理内容**：
1. リポジトリのチェックアウト
2. プラットフォーム固有の依存関係インストール
3. csourcesからのNimコンパイラビルド
4. kochビルドツールのコンパイル
5. コンパイラのブートストラップビルド
6. ドキュメント生成（koch doc）
7. GitHub Pagesへの公開（develブランチ、Linuxのみ）

**前後の処理との関連**：このワークフローは `ci/funs.sh` のユーティリティ関数に依存している。Windowsでは `ci/build_autogen.bat` を使用する。ドキュメント生成には `koch doc` コマンドを使用し、内部で `tools/kochdocs.nim` が処理を行う。

**影響範囲**：doc/html ディレクトリにドキュメントが生成される。develブランチへのプッシュ時には、GitHub Pagesサイト（nim-lang.github.io/Nim）が更新される。

## バッチ種別

CI/CD（ドキュメント生成・公開）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 関連ファイル変更時 |
| 実行時刻 | コード変更タイミング |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Git push / Pull Request（特定パスの変更時） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions | リポジトリでGitHub Actionsが有効化されていること |
| GITHUB_TOKEN | GitHub Pagesへの公開に必要なシークレット |
| ランナー | GitHub提供のホステッドランナー（ubuntu-22.04, windows-latest, macos-15） |

### 実行可否判定

- 特定のパスの変更がある場合のみ実行される
- 同一ワークフローの同時実行は `concurrency` 設定により制御される（進行中のものはキャンセル）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| target | マトリクス | Yes | - | ターゲットプラットフォーム（linux/windows/osx） |
| os | マトリクス | Yes | - | ランナーのOSイメージ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config/build_config.txt | テキスト | csourcesのバージョン情報 |
| ci/funs.sh | シェルスクリプト | ユーティリティ関数 |
| ci/build_autogen.bat | バッチファイル | Windows用csourcesビルド |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| doc/html | HTMLファイル | 生成されたドキュメント |
| GitHub Pages | Webサイト | 公開されたドキュメント（develブランチ、Linuxのみ） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各種.htmlファイル |
| 出力先 | doc/html |
| 文字コード | UTF-8 |
| 区切り文字 | N/A（HTML） |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ fetchDepth: 2
2. 依存関係インストール
   └─ macOS: brew install make
   └─ Windows: MinGW/DLLインストール
3. PATH設定
   └─ bin/ をPATHに追加
4. システム情報出力
   └─ nimCiSystemInfo
5. csourcesビルド
   └─ POSIX: nimBuildCsourcesIfNeeded
   └─ Windows: ci/build_autogen.bat
6. kochビルド
   └─ nim c koch
7. コンパイラビルド
   └─ ./koch boot -d:release
8. ドキュメント生成
   └─ ./koch doc --git.commit:devel
9. GitHub Pages公開
   └─ develブランチ + Linux のみ
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[リポジトリチェックアウト]
    B --> C{macOS?}
    C -->|Yes| D[brew install make]
    C -->|No| E{Windows?}
    D --> F[PATH設定]
    E -->|Yes| G[MinGW/DLLインストール]
    E -->|No| F
    G --> F
    F --> H[システム情報出力]
    H --> I{Windows?}
    I -->|Yes| J[ci/build_autogen.bat]
    I -->|No| K[nimBuildCsourcesIfNeeded]
    J --> L[koch ビルド]
    K --> L
    L --> M[koch boot]
    M --> N[koch doc]
    N --> O{devel && Linux?}
    O -->|Yes| P[GitHub Pages公開]
    O -->|No| Q[ワークフロー終了]
    P --> Q
```

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

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

該当なし（このバッチはデータベースを使用しない）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ビルドエラー | コンパイル失敗 | ログを確認して修正 |
| 1 | ドキュメント生成エラー | koch doc失敗 | ドキュメントソースを確認 |
| 1 | 依存関係エラー | パッケージインストール失敗 | CIを再実行 |
| タイムアウト | タイムアウト | 60分を超過 | 処理の最適化が必要 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actions設定に依存 |
| リトライ間隔 | 手動での再実行 |
| リトライ対象エラー | 一時的なネットワークエラー等 |

### 障害時対応

1. GitHub Actionsのログを確認
2. 失敗したステップを特定
3. ドキュメント生成エラーの場合、ドキュメントソースの問題を確認
4. 必要に応じてローカルで再現テスト

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース不使用） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ワークフロー実行あたり3ジョブ（linux/windows/osx） |
| 目標処理時間 | 60分以内（タイムアウト設定） |
| メモリ使用量上限 | GitHub提供のホステッドランナー依存 |

## 排他制御

- `concurrency` 設定により同一グループのワークフローが制御される
- `cancel-in-progress: true` により、同一PR/ブランチで新しいワークフローが開始されると進行中のものはキャンセル
- グループキー: `${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}`

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| システム情報 | ワークフロー開始時 | nimCiSystemInfo |
| コマンドログ | 各ステップ実行時 | 実行コマンドと結果 |
| ドキュメント生成ログ | koch doc実行時 | ドキュメント生成進捗 |
| エラーログ | エラー発生時 | 失敗原因の詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ実行時間 | 60分 | GitHub Actionsタイムアウト |
| ビルド成功率 | - | GitHub Actionsステータス |

## 備考

### トリガー対象パス

| パス | 説明 |
|------|------|
| `compiler/**.nim` | コンパイラソース |
| `config/nimdoc.cfg` | ドキュメント生成設定 |
| `doc/**.rst` | reStructuredTextドキュメント |
| `doc/**.md` | Markdownドキュメント |
| `doc/nimdoc.css` | ドキュメントスタイルシート |
| `lib/**.nim` | 標準ライブラリソース |
| `nimdoc/testproject/expected/testproject.html` | ドキュメントテストの期待値 |
| `tools/dochack/dochack.nim` | ドキュメントハックツール |
| `tools/kochdocs.nim` | kochドキュメント生成モジュール |
| `.github/workflows/ci_docs.yml` | このワークフロー自体 |
| `koch.nim` | kochビルドツール |

### マトリクス構成

| target | os | 説明 |
|--------|-----|------|
| linux | ubuntu-22.04 | Linux環境（GitHub Pages公開対象） |
| windows | windows-latest | Windows環境 |
| osx | macos-15 | macOS環境 |

### GitHub Pages公開条件

- `github.event_name == 'push'`
- `github.ref == 'refs/heads/devel'`
- `matrix.target == 'linux'`

これらの条件をすべて満たす場合のみ、`crazy-max/ghaction-github-pages@v4` アクションでGitHub Pagesに公開される。
