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

TypeDocのこと

[TypeDoc][td]という[TypeScript][ts]用のドキュメント生成器があります(npm i -g typedoc)。
[ts]: https://basarat.gitbooks.io/typescript/
[td]: http://typedoc.io/
[tdin]: http://typedoc.io/guides/installation.html
[tsconfig]: https://github.com/Microsoft/TypeScript/wiki/tsconfig.json

設定の方法

コマンド引数

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

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

gulp/gruntの設定中に含める

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

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

[tsconfig.json][tsconfig]のようにコマンドのフラグを保存する方法がないか探したところ、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がありました。記事自体はオープンのままですが、どうも[こっそり][commit][実装されている][tsconfigjs]ようです。

"typedocOptions"というキーで含めればいいようなので、試してからまた追記します。
[commit]: https://github.com/sebastian-lenz/typedoc/commit/a36d71281702eea70f352d1c87d53ae921d7c549
[tsconfigjs]: https://github.com/sebastian-lenz/typedoc/blob/e44be23a9d16cc8c976747ca748916416f000183/src/lib/utils/options/readers/tsconfig.js

todo

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

リンク

• [TypeScript][ts]
• [TypeDoc][td]
• Support tsconfig.json #130