# 画面設計書 5-nim doc（ドキュメント生成）

## 概要

本ドキュメントは、NimソースコードからHTMLドキュメントを生成するサブコマンド`nim doc`のCLIインターフェース設計書です。

### 本画面の処理概要

`nim doc`コマンドは、Nimソースコード内のドキュメントコメント（`##`で始まるコメント）を解析し、HTMLフォーマットのAPIドキュメントを自動生成するサブコマンドです。reStructuredTextおよびMarkdown形式のマークアップをサポートし、シンタックスハイライト、クロスリファレンス、目次生成などの機能を提供します。

**業務上の目的・背景**：Nimライブラリやモジュールの利用者向けドキュメントを自動生成します。ソースコード内にドキュメントを記述することで、コードとドキュメントの同期を維持しやすくなります。標準ライブラリのドキュメントもこのツールで生成されています。

**画面へのアクセス方法**：ターミナルから`nim doc <filename.nim>`を実行します。

**主要な操作・処理内容**：
1. Nimソースファイルの解析
2. ドキュメントコメント（`##`）の抽出
3. reStructuredText/Markdownのパース
4. 型・プロシージャ等のシグネチャ抽出
5. HTMLテンプレートへの適用
6. 最終HTMLファイルの出力
7. インデックスファイルの生成（オプション）

**画面遷移**：
- 入力元：`nim`メインコマンドから`cmdDoc`として呼び出し
- 遷移先：なし（生成完了後終了）、`--run`オプション時はブラウザで表示

**権限による表示制御**：OSのファイルシステム権限に依存。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ドキュメント生成 | 主機能 | ソースコードからHTMLドキュメントを自動生成する処理 |

## 画面種別

CLIサブコマンド（ドキュメント生成ツール）

## URL/ルーティング

```
nim doc [options] <projectfile.nim>
nim doc2 [options] <projectfile.nim>
```

オプション例：
- `nim doc hello.nim` - ドキュメント生成
- `nim doc --project hello.nim` - プロジェクト全体のドキュメント
- `nim doc --index:on hello.nim` - インデックス付き
- `nim doc -r hello.nim` - 生成後ブラウザで開く
- `nim doc --outdir:docs hello.nim` - 出力ディレクトリ指定

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| projectfile | string | 入力 | はい | ドキュメント生成対象のNimソースファイル |
| --project | flag | 入力 | いいえ | プロジェクト全体を処理 |
| --index:on | flag | 入力 | いいえ | インデックス生成 |
| --outdir:DIR | string | 入力 | いいえ | 出力ディレクトリ |
| -r | flag | 入力 | いいえ | 生成後ブラウザで開く |
| *.html | file | 出力 | - | 生成されたHTMLドキュメント |
| theindex.html | file | 出力 | - | インデックスファイル（オプション） |

## 表示項目

| 項目 | 説明 | 表示条件 |
|------|------|----------|
| Hint: [Success] | 生成成功と出力パス | デフォルト |
| 処理中ファイル | ドキュメント生成中のモジュール | --verbosity:1以上 |
| RST警告 | reStructuredTextパース警告 | 問題発生時 |

## イベント仕様

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

`main.nim`の`cmdDoc`ケースで処理されます：

1. `wantMainModule(conf)` - メインモジュール要求
2. `loadConfigs(DocConfig, ...)` - nimdoc.cfg読み込み
3. `defineSymbol(conf.symbols, "nimdoc")` - nimdocシンボル定義
4. `commandDoc2(graph, HtmlExt)` - ドキュメント生成実行

### 2-ドキュメント解析

docgen.nimの処理：
- `TDocumentor`型（行79-111）がドキュメント生成器
- `genComment`: ドキュメントコメント抽出（行434-448）
- `genRecComment`: 再帰的コメント抽出（行463-471）
- `parseRst`: reStructuredTextパース（行305-308）

### 3-HTML生成

rstgen.nimと連携：
- `RstGenerator`型でHTML/LaTeX生成
- シンタックスハイライト適用
- クロスリファレンスリンク生成

### 4-出力

- `commandBuildIndex`（`--genIndex`時）でインデックス生成
- `openDefaultBrowser`（`-r`オプション時）でブラウザ表示

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

本CLIツールはデータベースを使用しません。

### ファイルシステム操作

| 操作 | 対象 | 種別 | 概要 |
|------|------|------|------|
| 解析 | *.nim | READ | Nimソースファイル読み込み |
| 設定 | nimdoc.cfg | READ | ドキュメント設定読み込み |
| 出力 | htmldocs/*.html | WRITE | HTMLドキュメント出力 |
| 出力 | theindex.html | WRITE | インデックスファイル出力 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|----------|
| ヒント | "Hint: [Success] ..." | 生成成功時 |
| 警告 | "warnRstRedefinitionOfLabel" | ラベル重複時 |
| 警告 | "warnRstBrokenLink" | リンク切れ時 |
| 警告 | "warnRstUnknownSubstitution" | 不明な置換時 |

## 例外処理

| 状態 | エラーメッセージ | 処理 |
|------|-----------------|------|
| ソースファイル不在 | "cannot open file: $1" | エラー終了 |
| RST構文エラー | RST固有のエラーメッセージ | 警告表示（継続） |
| 設定ファイルエラー | 設定関連エラー | エラー終了 |

## 備考

- `##`で始まるコメントがドキュメントコメント
- reStructuredTextとMarkdownの両方をサポート
- `{.doctype: markdown.}`プラグマでMarkdownモード強制
- `runnableExamples`ブロックでコード例を実行可能に
- `--docInternal`で非公開シンボルもドキュメント化
- LaTeX出力は`nim doc2tex`コマンドで可能

---

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

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

### 推奨読解順序

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

ドキュメント生成で使用される主要なデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | docgen.nim | `compiler/docgen.nim` | TDocumentor型（行79-111）、PDoc型（行111） |
| 1-2 | docgen.nim | `compiler/docgen.nim` | Item型、ModSection型（行48-64） |

**読解のコツ**: TDocumentorはRstGeneratorを継承し、Nimドキュメント固有の情報を追加。modDescPreはモジュール説明、sectionは各種シンボルのドキュメントを保持。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.nim | `compiler/main.nim` | cmdDocケース（行332-341） |
| 2-2 | main.nim | `compiler/main.nim` | commandDoc2関数（行101-112） |

**主要処理フロー**:
1. **main.nim 行332-341**: `docLikeCmd`テンプレート内で処理
2. **main.nim 行334**: 警告設定調整
3. **main.nim 行339**: `commandDoc2(graph, HtmlExt)`呼び出し
4. **main.nim 行340-341**: `--genIndex`時にインデックス生成

#### Step 3: ドキュメント解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | docgen.nim | `compiler/docgen.nim` | genComment関数（行434-448） |
| 3-2 | docgen.nim | `compiler/docgen.nim` | genRecComment関数（行463-471） |
| 3-3 | docgen.nim | `compiler/docgen.nim` | parseRst関数（行305-308） |

**主要処理フロー**:
- **行434-448**: `genComment`でノードからコメント抽出
- **行463-471**: `genRecComment`で再帰的にコメント検索
- **行305-308**: `parseRst`でreStructuredTextパース

#### Step 4: HTML生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | docgen.nim | `compiler/docgen.nim` | newDocumentor関数（行324-421） |
| 4-2 | rstgen.nim | `packages/docutils/rstgen.nim` | RstGenerator型、HTML生成 |

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

```
main.nim::mainCommand()
    │
    └─ case cmdDoc
           │
           └─ docLikeCmd
                  │
                  ├─ loadConfigs(DocConfig)
                  │
                  ├─ defineSymbol("nimdoc")
                  │
                  └─ commandDoc2(graph, HtmlExt)
                         │
                         ├─ setPipeLinePass(Docgen2Pass)
                         │
                         └─ compilePipelineProject()
                                │
                                └─ docgen処理
                                       │
                                       ├─ genComment()
                                       │
                                       ├─ parseRst()
                                       │
                                       └─ HTML出力
```

### データフロー図

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

*.nim ───▶ レキサー/パーサー ───▶ AST
                 │
                 ▼
AST ───▶ genComment() ───▶ ドキュメントコメント抽出
                 │
                 ▼
コメント ───▶ parseRst() ───▶ RST/Markdown AST
                 │
                 ▼
RST AST ───▶ RstGenerator ───▶ HTML文字列
                 │
                 ├─ シンタックスハイライト
                 │
                 └─ クロスリファレンス
                 │
                 ▼
HTML文字列 ───▶ テンプレート適用 ───▶ *.html
                 │
                 ▼ (--genIndex)
         インデックス生成 ───▶ theindex.html
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| docgen.nim | `compiler/docgen.nim` | ソース | ドキュメント生成メインロジック |
| main.nim | `compiler/main.nim` | ソース | commandDoc2関数 |
| rstgen.nim | `packages/docutils/rstgen.nim` | ソース | RST→HTML変換 |
| rst.nim | `packages/docutils/rst.nim` | ソース | reStructuredTextパーサー |
| rstast.nim | `packages/docutils/rstast.nim` | ソース | RST AST定義 |
| nimdoc.cfg | `config/nimdoc.cfg` | 設定 | ドキュメント生成設定 |
| nimdoc.css | `doc/nimdoc.css` | スタイル | ドキュメントCSS |
