# 画面設計書 13-koch docs

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch docs`サブコマンドの画面設計書です。Nimプロジェクト全体のHTMLドキュメントを生成する処理について説明します。

### 本画面の処理概要

`koch docs`は、Nimコンパイラとその標準ライブラリのHTMLドキュメントを一括生成するCLIサブコマンドです。Markdownファイル、Nimソースコード、およびパッケージドキュメントからHTML形式のドキュメントを生成し、インデックスファイルも作成します。

**業務上の目的・背景**：Nimプロジェクトのドキュメントは、言語仕様、標準ライブラリAPI、チュートリアルなど多岐にわたります。これらを個別に生成するのは非効率であり、`koch docs`により一括でドキュメントを生成・更新できます。生成されたドキュメントはWebサイト（nim-lang.org）で公開されるほか、ローカルでの参照にも使用されます。

**画面へのアクセス方法**：ターミナルから以下のコマンドを実行します。
```
koch docs [options]
```

**主要な操作・処理内容**：
1. JSファイルのビルド（nimblepkglist.js、dochack.js）
2. 公式パッケージのクローン（asyncftpclient、punycode、smtp等）
3. 出力ディレクトリの作成
4. ドキュメントサンプルのビルド
5. インデックスファイル（.idx）の生成
6. トップレベルインデックス（theindex.html）の生成
7. コンパイラパッケージドキュメントの生成
8. HTMLドキュメントの生成
9. overview.htmlをindex.htmlにコピー
10. dochack.jsのコピー

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: なし（ドキュメント生成完了後は自動的に終了）
- 関連: nim doc（No.5）コマンドが内部で使用される

**権限による表示制御**：特別な権限制御はありません。ネットワーク接続が必要です（公式パッケージのクローン用）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | ドキュメントビルド | 主機能 | プロジェクト全体のドキュメント生成処理 |
| 9 | ドキュメント生成 | 補助機能 | nim docを呼び出してドキュメント生成 |

## 画面種別

CLIコマンド実行画面（バッチ処理型）

## URL/ルーティング

```
koch docs [options]
koch doc [options]
```

コマンドラインオプション:
- `--localdocs[:path]`: ローカルドキュメントのみ生成。パス指定で出力先を変更可能
- 標準のNimコンパイラオプションがそのまま渡される

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| options | string | いいえ | コンパイラに渡すオプション文字列 |
| --localdocs | flag | いいえ | ローカルドキュメントのみ生成 |
| --localdocs:path | string | いいえ | 出力先パスを指定 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc/html/ | directory | ローカルドキュメント出力先 |
| web/upload/{version}/ | directory | Web公開用ドキュメント出力先 |
| theindex.html | file | 全体インデックスファイル |
| index.html | file | トップページ（overview.htmlのコピー） |
| *.html | files | 各モジュールのHTMLドキュメント |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| コンパイルコマンド | 実行されるnimコンパイルコマンド |
| クローン進捗 | パッケージクローンの進捗 |

## イベント仕様

### 1-ドキュメント生成開始

```
koch docs
```

1. `buildDocs()`関数が呼び出される
2. ローカルドキュメントとWeb公開用ドキュメントの両方を生成
3. Google Analyticsコードが自動的に除去される（ローカル用）

### 2-ローカルドキュメントのみ生成

```
koch docs --localdocs
```

1. `buildDocs(localOnly=true)`が呼び出される
2. Web公開用ドキュメントは生成されない
3. 出力先はdoc/html/または指定パス

## データベース更新仕様

本コマンドはデータベースを使用しません。

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クローン | pkgs/* | CREATE | 公式パッケージのクローン |
| 生成 | doc/html/*.html | CREATE/UPDATE | HTMLドキュメント生成 |
| 生成 | doc/html/*.idx | CREATE/UPDATE | インデックスファイル生成 |
| コピー | doc/html/index.html | CREATE/UPDATE | overview.htmlからコピー |
| 生成 | web/upload/{ver}/*.html | CREATE/UPDATE | Web公開用ドキュメント |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | ::group::{desc} | GitHub Actionsでの折りたたみ開始 |
| MSG002 | 情報 | nim doc ... | ドキュメント生成コマンド |
| MSG003 | 情報 | nim md2html ... | Markdown変換コマンド |
| MSG004 | 情報 | nim buildIndex ... | インデックス生成コマンド |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| ネットワークエラー | 公式パッケージへの接続失敗 | ネットワーク設定を確認 |
| コンパイルエラー | ドキュメントコメントにエラーがある | エラーメッセージを表示して続行 |
| ディスク容量不足 | ドキュメント出力先の容量不足 | ディスク空き容量を確保 |

## 備考

- ドキュメント生成には数分かかります（マルチプロセス実行）
- `--errormax:3`により最初の3件のエラーのみ表示
- xelatexがインストールされている場合、PDF生成も可能（`koch pdf`）

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

ドキュメント生成で使用される定数とファイルリストを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kochdocs.nim | `tools/kochdocs.nim` | 定数定義（L15-23）: gaCode、nimArgs、gitUrl、docHtmlOutput等 |
| 1-2 | kochdocs.nim | `tools/kochdocs.nim` | L114-183: mdPdfList、withoutIndex、ignoredModules、officialPackagesListの定義 |

**読解のコツ**: ドキュメント対象ファイルはホワイトリスト/ブラックリスト形式で管理されています。

#### Step 2: エントリーポイントを理解する

docsコマンドの呼び出し処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | L747: "docs"コマンドの処理 |
| 2-2 | kochdocs.nim | `tools/kochdocs.nim` | buildDocs関数（L374-389）: メインエントリーポイント |

**主要処理フロー**:
1. **L374-379**: 出力ディレクトリの決定（デフォルトはdoc/html）
2. **L383-384**: Web公開用ドキュメントの生成（localOnlyでない場合）
3. **L386-387**: Google Analyticsコードの除去
4. **L389**: ローカルドキュメントの生成

#### Step 3: ドキュメントビルド処理を理解する

buildDocsDirおよび関連関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kochdocs.nim | `tools/kochdocs.nim` | buildDocsDir関数（L349-372）: ドキュメント生成のコア処理 |
| 3-2 | kochdocs.nim | `tools/kochdocs.nim` | buildDoc関数（L267-308）: HTMLドキュメント生成 |
| 3-3 | kochdocs.nim | `tools/kochdocs.nim` | buildDocPackages関数（L246-265）: パッケージドキュメント生成 |

**主要処理フロー**:
- **L351**: `buildJS()`でJSファイルをビルド
- **L352**: `gitClonePackages()`で公式パッケージをクローン
- **L353**: 出力ディレクトリの作成
- **L354**: `buildDocSamples()`でサンプルドキュメント生成
- **L357**: `buildDoc(indexOnly=true)`でインデックス生成
- **L359**: `buildIndex`コマンドでtheindex.html生成
- **L365**: `buildDocPackages()`でパッケージドキュメント生成
- **L368-369**: `buildDoc(indexOnly=false)`でHTML生成
- **L371**: overview.htmlをindex.htmlにコピー

#### Step 4: マルチプロセス実行を理解する

並列ドキュメント生成処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kochdocs.nim | `tools/kochdocs.nim` | mexec関数（L231-236）: マルチプロセス実行 |
| 4-2 | kochdocs.nim | `tools/kochdocs.nim` | sexec関数（L224-229）: シリアル実行（フォールバック） |

**主要処理フロー**:
- **L233**: `execProcesses()`でコマンドを並列実行
- **L234-236**: エラー時はシリアル実行でリトライ（ログ出力のため）

### プログラム呼び出し階層図

```
koch docs
    │
    └─ buildDocs(args, localOnly, localOutDir)
           │
           ├─ buildDocsDir(args, webUploadOutput/version)  # Web公開用
           │      │
           │      ├─ buildJS()                    # JSファイル生成
           │      │      └─ exec("nim js ...")
           │      │
           │      ├─ gitClonePackages()           # パッケージクローン
           │      │
           │      ├─ buildDocSamples()            # サンプル生成
           │      │      └─ exec("nim doc ...")
           │      │
           │      ├─ buildDoc(indexOnly=true)     # インデックス生成
           │      │      └─ mexec()               # 並列実行
           │      │
           │      ├─ exec("nim buildIndex ...")   # theindex.html
           │      │
           │      ├─ buildDocPackages(indexOnly)  # パッケージドキュメント
           │      │      └─ exec("nim doc --project ...")
           │      │
           │      ├─ buildDoc(indexOnly=false)    # HTML生成
           │      │      └─ mexec()
           │      │
           │      └─ copyFile()                   # index.html, dochack.js
           │
           └─ buildDocsDir(args, docHtmlOutput)   # ローカル用
                  └─ (同上)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

コマンドライン引数 ──────▶ parseopt処理 ────────────────▶ args, localOnly

doc/*.md ──────────────────▶ nim md2html ────────────────▶ doc/html/*.html

lib/**/*.nim ──────────────▶ nim doc ────────────────────▶ doc/html/*.html

pkgs/**/*.nim ─────────────▶ nim doc --index ────────────▶ doc/html/*.idx

doc/html/*.idx ────────────▶ nim buildIndex ─────────────▶ doc/html/theindex.html

doc/html/overview.html ────▶ copyFile() ─────────────────▶ doc/html/index.html

tools/dochack.js ──────────▶ copyFile() ─────────────────▶ doc/html/dochack.js
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kochdocs.nim | `tools/kochdocs.nim` | ソース | ドキュメント生成処理のメイン |
| koch.nim | `koch.nim` | ソース | docsコマンドの呼び出し |
| officialpackages.nim | `tools/officialpackages.nim` | ソース | 公式パッケージのクローン処理 |
| nimblepkglist.nim | `tools/nimblepkglist.nim` | ソース | パッケージリストJS生成 |
| docgen_sample.nim | `doc/docgen_sample.nim` | ソース | ドキュメント生成サンプル |
| nimdoc.cfg | `config/nimdoc.cfg` | 設定 | ドキュメント生成設定 |
| compiler/index.nim | `compiler/index.nim` | ソース | コンパイラドキュメントのエントリーポイント |
