TypeDocのこと

TypeDocというTypeScript用のドキュメント生成器があります(npm i -g typedoc)。

設定の方法

コマンド引数

インストールすると、例によってtypedocというCLIのツールが用意されており、設定をコマンド引数で渡すことができます。

typedocはデフォルトでもある程度素敵な出力をしてくれますが、d.tsを含めるか無視するかを切り替えたり(--includeDeclarations)や、ページをファイル単位にするかモジュール単位にするか(--mode)など、なかなか気の利いた設定項目があります。

gulp/gruntの設定中に含める

インストールの説明ページにはgulpとgruntの設定例が書いてあります。ただ、付属のtypedocコマンドを直接使う場合については、設定をコマンドラインで渡す方法以外の記述がありません。

typedoc.jsというファイルを用意する

tsconfig.jsonのようにコマンドのフラグを保存する方法がないか探したところ、typedoc.jsというファイルを用意すればそれを読んでくれるようでした。--optionsフラグでファイル名を指定することもできるようです(よく見るとヘルプに出ていました)。

typedocのヘルプ

$ typedoc 
(...)
--options    Specify a js option file that should be loaded.
If not specified TypeDoc will look for 'typedoc.js' in the current directory.

typedoc.jsの形式

typedoc.jsの雛形が見当たらなかったので、中身を見ながら試したところ、オブジェクトをエクスポートすればいいようです。

typedoc.js

module.exports = {
  "name": "hogeproject",
  "out": "doc",
  "mode": "file",
  "includeDeclarations": true,
  "hideGenerator": false
}

他に、関数をエクスポートすれば直接TypeDoc.Applicationオブジェクトを引数として呼び出されるようです。

tsconfig.json中に書く

「設定ファイルを別に設けるよりもtsconfig.jsonに含めてはどうか？」というissueがありました。記事自体はオープンのままですが、どうもこっそり実装されているようです。

"typedocOptions"というキーで含めればいいようなので、試してからまた追記します。

todo

ファイル内容をインラインで含める機能もあるようなのですが、ヘルプで見つけられなかったので今度探そうと思います。

タスクランナを経由せずTypeDocの設定をファイルに保存する