この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
こんにちは。サービスグループの武田です。
プログラムのドキュメントを生成する手法のひとつとして、ソースコードにコメントを書き、ツールでドキュメントをビルドするという方法があります。Javaなどの言語では標準でツールが提供されています。今回はTypeScriptのドキュメントを生成したいなと思い調べたところ、TypeDocが良さそうだったのでVueプロジェクトに導入してみました。TypeDocはMarkdownが使えるのもイマドキです。
環境
今回の検証環境は次のような環境になっています。
$ node -v
v10.16.0
$ vue -V
3.9.3
$ sw_vers
ProductName: Mac OS X
ProductVersion: 10.14.5
BuildVersion: 18F132
そのほか、主なモジュールのバージョンは以下となっています。また、vueコマンドがインストールされていない場合は、npm install -g @vue/cli
でインストールします。
- vue@2.6.10
- typedoc@0.14.2
- typedoc-webpack-plugin@1.1.4
プロジェクトを作成
まずはVue CLIを利用してプロジェクトを作成します。
$ vue create example-vue-typedoc
presetはManualにして、Linter以外はすべてデフォルトを選択します。LinterはESLintを選択しています。
最後の項目を選択するとインストールが始まります。インストールが終わったら、準備完了です。
今回のソースコード全体はGitHubに上げてあります。
Exampleクラスを書いてドキュメントを生成してみる
まずは次のようなクラスを作ってみます。内容は特にありません。
src/Example.ts
/**
* TypeDocのExampleです。
*/
export default class Example {
/** プロパティです。 */
public message: string = 'Hello';
/**
* メソッドです。
* @returns メッセージ
*/
public sayMessage(): string {
return this.message;
}
}
続いてTypeDocをインストールします。
$ npm install -D typedoc
インストールできたら、さっそくドキュメントを生成してみましょう。オプションがいろいろありますが、詳細は公式のリファレンスを参照してください。ここでは一番シンプルにやってみます。
$ ./node_modules/.bin/typedoc --out docs src/
$ open docs/index.html
不要なファイルのドキュメントも出力されてますが、とりあえずは成功と言えそうです。
TypeDocをwebpackと連携させる
Vue CLIで作成したプロジェクトは内部的にwebpackを使用しています。またTypeDocにはwebpackと連携させるためのプラグインが提供されています。つまり、Vue CLIのプロジェクトにプラグインを導入することで、簡単にドキュメントの生成ができます。
それでは連携させていきます。次のコマンドでtypedoc-webpack-pluginをインストールします。
$ npm install -D typedoc-webpack-plugin
次にwebpackの設定をします。Vue CLIで作成したプロジェクトでは、プロジェクトルート直下にvue.config.jsを用意することでオートロードされます。プラグインの引数でTypeDocのオプションを細かく指定できます。
vue.config.js
const TypedocWebpackPlugin = require('typedoc-webpack-plugin');
module.exports = {
configureWebpack: {
plugins: [
new TypedocWebpackPlugin({
name: 'example-vue-typedoc',
mode: 'file',
includeDeclarations: false,
ignoreCompilerErrors: true,
excludeNotExported: true,
}, './src/'),
],
},
};
それではプロジェクトをビルドします。ビルドすると自動的にドキュメントも生成されます。
$ npm run build
$ open dist/docs/index.html
すっきりとしたドキュメントが生成されました!
まとめ
多人数での開発ではもちろんですが、個人での開発でも、明日の自分のためにドキュメントを書いておくのが好ましいです。またJavaScriptと違い、型定義を自分でコメントに書く必要がないのでTypeScriptとTypeDoc最高ですね。