# バッチ設計書 23-koch.nim（docs）

## 概要

本ドキュメントは、Nimコンパイラの完全なドキュメントセットを生成するバッチ処理「koch docs」の設計書です。kochコマンドのdocsサブコマンドとして実行され、APIリファレンス、チュートリアル、マニュアル等のHTML形式ドキュメントを生成します。

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

**業務上の目的・背景**：Nimプログラミング言語の利用者が言語仕様、標準ライブラリAPI、ツール使用方法を理解するためには、包括的なドキュメントが不可欠です。本バッチは、ソースコードに含まれるドキュメントコメント（docstring）やMarkdownファイルからHTMLドキュメントを自動生成し、一貫性のあるドキュメントセットを提供します。これにより、開発者の学習効率向上とコミュニティの成長を支援します。

**バッチの実行タイミング**：リリース作業時、またはドキュメント更新時に手動で実行します。CI/CD（GitHub Actions）でもコンパイラやドキュメント変更時に自動実行されます。

**主要な処理内容**：
1. JavaScriptファイルのビルド（nimblepkglist.js、dochack.js）
2. 公式パッケージ（asyncftpclient, smtp, db_connector等）のクローン
3. ドキュメントサンプルのビルド（docgen_sample.nim）
4. インデックスファイル（.idx）の生成
5. トップレベルインデックス（theindex.html）の生成
6. コンパイラドキュメントの生成
7. 標準ライブラリドキュメントの生成
8. Markdownファイル（マニュアル、チュートリアル等）のHTML変換
9. 最終的なHTML出力とインデックスページの設定

**前後の処理との関連**：
- 前提バッチ：koch boot（コンパイラビルド）が完了していること
- 後続バッチ：GitHub Pagesへの公開、webUploadディレクトリからのアップロード

**影響範囲**：doc/html/配下にローカルドキュメントが生成されます。--localdocsオプションなしの場合、web/upload/{version}/配下にも公開用ドキュメントが生成されます。

## バッチ種別

ドキュメント生成 / レポート生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時、ドキュメント更新時） |
| 実行時刻 | 任意 / CI実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CI自動実行（GitHub Actions） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Nimコンパイラ | bin/nim が存在すること（koch bootで生成済み） |
| Git | Gitコマンドが利用可能であること（公式パッケージのクローンに使用） |
| ネットワーク接続 | 公式パッケージをGitHubからクローンするため必要 |

### 実行可否判定

特別な実行可否判定は行われません。Nimコンパイラが存在しない場合は処理中にエラーとなります。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --localdocs | フラグ | No | false | ローカルドキュメントのみ生成（公開用を生成しない） |
| --localdocs:path | 文字列 | No | doc/html | ローカルドキュメントの出力先パス |
| args | string | No | "" | nimコマンドに渡す追加引数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| lib/**/*.nim | Nimソースファイル | 標準ライブラリのソースコード（docstringを抽出） |
| compiler/**/*.nim | Nimソースファイル | コンパイラのソースコード |
| doc/**/*.md | Markdownファイル | マニュアル、チュートリアル等 |
| nimsuggest/sexp.nim | Nimソースファイル | nimsuggestのsexp実装 |
| pkgs/**/*.nim | Nimソースファイル | 公式パッケージのソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| doc/html/ | HTMLファイル群 | ローカル用ドキュメント |
| web/upload/{version}/ | HTMLファイル群 | 公開用ドキュメント（--localdocs指定時は生成しない） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | HTML、CSS、JavaScript |
| 出力先 | doc/html/ または指定パス |
| 文字コード | UTF-8 |
| インデックス | theindex.html、index.html（overview.htmlのコピー） |

## 処理フロー

### 処理シーケンス

```
1. buildJS()
   └─ nimblepkglist.jsをビルド（web/upload/用）
   └─ dochack.jsのパスを取得

2. gitClonePackages()
   └─ 公式パッケージをpkgs/配下にクローン
   └─ asyncftpclient, punycode, smtp, db_connector, checksums, atlas, htmlparser

3. createDir(destPath)
   └─ 出力ディレクトリを作成

4. buildDocSamples(args, destPath)
   └─ doc/docgen_sample.nimのドキュメント生成

5. buildDoc(args, destPath, indexOnly=true)
   └─ 全ドキュメントの.idxファイルを生成
   └─ Markdownファイル（doc/*.md）の変換
   └─ 標準ライブラリ（lib/**/*.nim）のドキュメント生成
   └─ 公式パッケージのドキュメント生成

6. nim buildIndex
   └─ theindex.htmlを生成

7. buildDocPackages(args, destPath, indexOnly=true)
   └─ コンパイラドキュメントのインデックス生成

8. buildDoc(args, destPath, indexOnly=false)
   └─ 全ドキュメントのHTML生成（本番）

9. buildDocPackages(args, destPath, indexOnly=false)
   └─ コンパイラドキュメントのHTML生成

10. copyFile(overview.html, index.html)
    └─ overview.htmlをindex.htmlとしてコピー

11. copyFile(dochack.js)
    └─ JavaScriptファイルをコピー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[buildJS]
    B --> C[gitClonePackages]
    C --> D[出力ディレクトリ作成]
    D --> E[buildDocSamples]
    E --> F[buildDoc - インデックス生成]
    F --> G[nim buildIndex]
    G --> H[buildDocPackages - インデックス]
    H --> I[buildDoc - HTML生成]
    I --> J[buildDocPackages - HTML]
    J --> K[index.htmlコピー]
    K --> L[dochack.jsコピー]
    L --> M{localOnly?}
    M -->|Yes| N[バッチ終了]
    M -->|No| O[公開用ドキュメント生成]
    O --> N
```

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

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

本バッチはデータベースを使用しません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンパイルエラー | ソースコードの構文エラー | エラーメッセージに従いソースを修正 |
| - | Git clone失敗 | ネットワーク接続エラー | ネットワーク接続を確認 |
| - | ファイル不在 | 必要なソースファイルが存在しない | 欠損ファイルを確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | Git cloneのみretryCallで自動リトライ |
| リトライ間隔 | gitutils.nimのretryCall実装による |
| リトライ対象エラー | Gitコマンドの一時的な失敗 |

### 障害時対応

1. コンパイルエラーの場合：エラーメッセージを確認し、該当ソースを修正
2. ネットワークエラーの場合：接続を確認し再実行
3. 部分的な失敗の場合：失敗したファイルを特定し個別に対応

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ファイル操作のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（エラー時は中断、出力ファイルは残る） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数百のソースファイル、数十のMarkdownファイル |
| 目標処理時間 | 数分〜十数分（マシン性能・ファイル数による） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同時実行は想定していません。同一ディレクトリで複数のkoch docsを並列実行すると、出力ファイルが競合する可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各処理実行時 | 実行中のコマンド（echo出力） |
| エラーログ | エラー発生時 | コンパイルエラーの詳細 |
| GitHub Actions | CI実行時 | ::group::によるログ折りたたみ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | CI/CD実行時はGitHub Actionsで監視 |

## 備考

- nimArgsにはerrormax:3が設定されており、連続エラーは3件で打ち切り
- GoogleAnalyticsコード（gaCode）またはPlausible Analyticsコード（paCode）がドキュメントに埋め込まれる
- mexec関数により複数のドキュメント生成が並列実行される
- --localdocsオプションを使用すると公開用ドキュメントは生成されない
- 公開用ドキュメントにはGoogleAnalyticsが含まれるが、ローカル版には含まれない
- gitUrlとして https://github.com/nim-lang/Nim が参照される
- doc/配下の一部ファイル（docs.md, docstyle.md）は変換対象外
- lib/system/配下の大部分はインクルードファイルのためドキュメント生成対象外
- withoutIndexに指定されたファイルはインデックスに含まれない
- ignoredModulesに指定されたファイルはドキュメント生成対象外
