# 機能設計書: ドキュメントビルド (No.23)

## 1. 機能概要

### 1.1 機能名
ドキュメントビルド (koch.nim docs)

### 1.2 機能説明
Nimの公式ドキュメント（API リファレンス、マニュアル、チュートリアル等）をHTML/PDF形式で生成する機能。標準ライブラリ、コンパイラ、公式パッケージのドキュメントを一括生成し、インデックスページも自動作成する。

### 1.3 関連画面
- CLI（コマンドラインインターフェース）
- 生成されるHTML/PDFドキュメント

## 2. 機能詳細

### 2.1 入力
| 項目 | 型 | 必須 | 説明 |
|------|-----|------|------|
| args | string | No | 追加のnimコマンドオプション |
| --localdocs | flag | No | ローカルドキュメントのみ生成 |
| --localdocs:path | string | No | 出力先パス指定 |

### 2.2 処理フロー
1. **初期化**
   - nimArgs定数を構築（エラー設定、警告抑制等）
   - 出力ディレクトリを作成

2. **依存パッケージ取得**
   - gitClonePackages()で公式パッケージをクローン
     - asyncftpclient, punycode, smtp, db_connector, checksums, atlas, htmlparser

3. **ドキュメントサンプルビルド**
   - doc/docgen_sample.nimの変換

4. **インデックス生成（1回目）**
   - buildDoc()でindexOnly=trueを指定
   - 全.nimファイルから.idxファイル生成
   - nim buildIndexでtheindex.html生成

5. **パッケージドキュメント（インデックス）**
   - buildDocPackages()でcompiler/のドキュメントインデックス生成

6. **HTML生成（2回目）**
   - buildDoc()でindexOnly=falseを指定
   - 全.nimファイルからHTML生成
   - buildDocPackages()でパッケージHTMLを生成

7. **最終処理**
   - overview.htmlをindex.htmlとしてコピー
   - dochack.jsをコピー

### 2.3 出力
| 項目 | 型 | 説明 |
|------|-----|------|
| doc/html/ | directory | ローカルドキュメント出力先 |
| web/upload/{version}/ | directory | Web公開用出力先 |
| theindex.html | file | 全体インデックス |
| *.html | files | 各モジュールのHTML |
| doc/pdf/*.pdf | files | PDFドキュメント（pdf コマンド時） |

### 2.4 エラーハンドリング
| エラー条件 | 処理 |
|------------|------|
| nimが見つからない | findNimImpl()でPATH検索後にエラー |
| xelatexがない（PDF） | assertで失敗 |
| ドキュメント生成エラー | errormax:3で最大3エラーまで続行 |

## 3. ビジネスルール

### 3.1 ドキュメント対象

#### 標準ライブラリ（lib/）
- lib/pure/, lib/std/, lib/core/ 配下の.nimファイル
- 除外: nimcache, includes, deprecated, genode

#### 除外モジュール
```
lib/pure/future.nim
lib/pure/collections/hashcommon.nim
lib/pure/collections/tableimpl.nim
lib/posix/posix_*.nim
lib/pure/md5.nim
lib/std/sha1.nim
...
```

#### 公式パッケージ
```
pkgs/asyncftpclient/src/asyncftpclient.nim
pkgs/smtp/src/smtp.nim
pkgs/punycode/src/punycode.nim
pkgs/db_connector/src/db_connector/*.nim
pkgs/checksums/src/checksums/*.nim
pkgs/htmlparser/src/htmlparser.nim
```

### 3.2 Markdown対象ファイル
```
doc/*.md
pkgs/atlas/doc/atlas.md
```

### 3.3 PDF対象ファイル
```
doc/manual.md
doc/lib.md
doc/tut1.md, tut2.md, tut3.md
doc/nimc.md
doc/niminst.md
doc/mm.md
```

## 4. 技術仕様

### 4.1 使用ライブラリ
- std/os, std/strutils, std/osproc
- std/sets, std/pathnorm, std/sequtils, std/pegs
- std/private/globs
- compiler/nimpaths

### 4.2 主要定数
```nim
const
  gaCode* = " --doc.googleAnalytics:UA-48159761-1"
  paCode* = " --doc.plausibleAnalytics:nim-lang.org"
  docDefines = "-d:nimExperimentalLinenoiseExtra"
  nimArgs = "--errormax:3 --hint:Conf:off ... -d:boot"
  gitUrl = "https://github.com/nim-lang/Nim"
  docHtmlOutput = "doc/html"
  webUploadOutput = "web/upload"
```

### 4.3 並列処理
```nim
proc mexec(cmds: openArray[string]) =
  let r = execProcesses(cmds, {poStdErrToStdOut, poParentStreams, poEchoCmd})
  if r != 0:
    echo "external program failed, retrying serial work queue for logs!"
    sexec(cmds)
```

### 4.4 PDF生成
```nim
proc nim2pdf(src: string, dst: string, nimArgs: string) =
  # nim md2texでTeX生成
  # xelatex 3回実行でクロスリファレンス解決
  # makeindexでインデックス生成
```

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

### 5.1 推奨読解順序

#### 5.1.1 データ構造の理解
1. **kochdocs.nim 14-24行目**: 定数定義
   - gaCode, nimArgs, gitUrl, docHtmlOutput等

2. **kochdocs.nim 126-184行目**: ドキュメント対象リスト
   - withoutIndex, ignoredModules, officialPackagesList

#### 5.1.2 エントリーポイント
3. **koch.nim 747行目**: docsコマンド処理
   ```nim
   of "doc", "docs": buildDocs(op.cmdLineRest & " --d:nimPreviewSlimSystem " & paCode, localDocsOnly, localDocsOut)
   ```

4. **kochdocs.nim 374-389行目**: buildDocs関数
   - メインエントリポイント

#### 5.1.3 コア処理
5. **kochdocs.nim 349-372行目**: buildDocsDir関数
   - 実際のドキュメント生成処理

6. **kochdocs.nim 267-308行目**: buildDoc関数
   - 各ファイルのnimコマンド生成と並列実行

7. **kochdocs.nim 246-265行目**: buildDocPackages関数
   - compiler/のドキュメント生成

### 5.2 読解のコツ

#### 2パス処理の理解
```nim
# 1回目: インデックス生成
buildDoc(args, dir, indexOnly=true)
exec(nim & " buildIndex -o:$1/theindex.html $1" % [dir])

# 2回目: HTML生成
buildDoc(args, dir, indexOnly=false)
```

#### mexec関数の理解
- 並列実行を試み、失敗時は逐次実行にフォールバック
- CI環境でのエラーログ取得に有効

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

```
koch docs [args]
  |
  +-- buildDocs(args, localOnly, localOutDir)
        |
        +-- buildDocsDir(args, webUploadOutput/version) [localOnly=false]
        |     |
        |     +-- buildJS()
        |     |     +-- nim js tools/nimblepkglist.nim
        |     |     +-- getDocHacksJs()
        |     |
        |     +-- gitClonePackages()
        |     +-- buildDocSamples()
        |     |
        |     +-- buildDoc(indexOnly=true)
        |     |     +-- mexec([nim doc --index:only ...])
        |     |
        |     +-- nim buildIndex -o:theindex.html
        |     +-- buildDocPackages(indexOnly=true)
        |     |
        |     +-- buildDoc(indexOnly=false)
        |     |     +-- mexec([nim doc ...])
        |     |
        |     +-- buildDocPackages(indexOnly=false)
        |     +-- copyFile(overview.html -> index.html)
        |
        +-- buildDocsDir(args, docHtmlOutput) [ローカル用]
```

### 5.4 データフロー図

```
[.nim ファイル群]
       |
       v
[getDocList()] --> [doc: seq[string]]
       |
       v
[buildDoc()]
  +-- for d in doc:
  |     nim doc --outdir:destPath d
  |
  +-- for d in withoutIndex:
  |     nim doc -o:destPath/name.html d
  |
  +-- for d in officialPackagesList:
        nim doc --outdir:destPath d
       |
       v
[.idx ファイル群] --> [nim buildIndex] --> [theindex.html]
       |
       v
[.html ファイル群]
       |
       v
[doc/html/ または web/upload/{version}/]
```

### 5.5 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| tools/kochdocs.nim | メイン | ドキュメント生成ロジック |
| koch.nim (747-751行目) | エントリ | kochからの呼び出し |
| tools/officialpackages.nim | 補助 | 公式パッケージ管理 |
| doc/*.md | 入力 | Markdownドキュメント |
| lib/**/*.nim | 入力 | 標準ライブラリソース |
| compiler/index.nim | 入力 | コンパイラドキュメント起点 |
| doc/html/ | 出力 | ローカルHTML出力 |
| web/upload/{version}/ | 出力 | Web公開用出力 |

## 6. 変更履歴

| 日付 | 変更者 | 変更内容 |
|------|--------|----------|
| 2026-02-17 | Claude | 初版作成 |
