Vue CLIで作成したプロジェクトにTypeDocを導入する

TypeScriptのドキュメントを生成したいなと思い調べたところ、TypeDocが良さそうだったのでVueプロジェクトに導入してみました。
2019.07.24

この記事は公開されてから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最高ですね。