TypeScriptのリファレンスドキュメント生成にtypedocが便利だった

typedocというツールで生成したリファレンスをGitHub Pagesに置く話。

JavaならJavadoc、C/C++ならDoxygen、Goならgodoc.org、JavaScriptならJSDocみたいにそれぞれドキュメント生成のための便利ツールやサービスがあったりする。
最近よくTypeScriptを書くのでドキュメント生成について調べた。

いくつか候補はあったがtypedocが一番活気があって良さそうだったので早速使ってみる。
公式サイトに書いてあるのでオプションの解説はしないけど結構柔軟に対応できそうだった。
（公式サイトがtypedoc.ioからtypedoc.orgに変わっているが一部古いドメインの記述が残っているのでちょっとアレ）

npm install typedoc -D
$(npm bin)/typedoc --mode file --readme none --target ES5 --out ./docs

これでdocsディレクトリにドキュメントのhtmlやらなにやらが生成されるので、これをそのままどこかに設置すればいい。

こういう時に便利なのがGitHub Pagesでgh-pagesというブランチを作ってそこにhtmlを置いておけば username.github.io/project-name でアクセスできるようになる。

GitHub Pagesの設置にはいくつか選択肢がある

masterブランチをドキュメントとして公開する (hoge-docsみたいな感じでドキュメント用にリポジトリを用意する場合)
masterブランチの/docsディレクトリをドキュメントとして公開する (リポジトリにドキュメントをバンドルするけどウェブにも置いておきたい場合)
他のブランチとヒストリを共有しないgh-pagesという名前のorphanブランチにプッシュして公開する (本体とドキュメントのブランチを分けたくないけどバンドルはしたくない場合)

今回はgh-pagesブランチを使ってホスティングすることにした。

annict.jsのドキュメント生成&公開スクリプト

という雑な感じでスクリプトを書いてプッシュしたら無事GitHub Pagesでホスティングされた。

出力されるリファレンスサイトの見た目はデフォルトではこんな感じ（テーマはオプションで変えられる）