はじめに

この記事では、TypeScriptのJSDoc（TSDoc）から、TypeDocとtypedoc-plugin-markdownを使ってMarkdown形式でドキュメントを自動的に生成する方法を解説します。

この記事の方法を使うと、ソースコードのJSDocから画像のようなドキュメントをMarkdown形式で自動生成できます。
実際に私が自動生成したドキュメントはここから閲覧できます。

なお、ドキュメントを1つのファイルにまとめるオプションは用意されていないようです。

この記事で解説しないこと

次の内容については、この記事で扱いません。

始める前にまず、TypeScriptの環境を構築しておいてください。また、TypeScriptのソースコードに書かれているJSDocと型情報からドキュメントを生成するため、事前にそれらが整備されている必要があります。

依存関係としてtypedocとtypedoc-plugin-markdownをインストールします。

npm install --save-dev typedoc typedoc-plugin-markdown

ここまで来れば、ほぼ完成です。あとはコマンドを実行するだけでdocsディレクトリーにドキュメントが自動で生成されます。

エントリーポイントのTypeScriptファイルのパスは、プロジェクトに合わせて読み替えてください。

npx typedoc --plugin typedoc-plugin-markdown "src/index.ts"

よく使いそうなオプションを簡単に解説します。すべてのオプションとその説明は、npx typedoc --helpを実行するか、公式サイトから閲覧できます。

ドキュメントを出力するディレクトリーを指定します。デフォルトはdocsです。

このオプションを指定すると、出力先のディレクトリーを一度空にしてからドキュメントを生成します。

このオプションを指定すると、privateな変数やメソッドをドキュメントに載せないようにします。このオプションを指定しなかった場合は、privateな変数やメソッドも掲載されます。

内部向けのドキュメントでは指定せず、ライブラリーなどの利用者向けのドキュメントでは指定するといった使い分けになりそうです。

このオプションを指定すると、ドキュメントにバージョンを記載します。バージョンはpackage.jsonのversionの値が使われます。

このオプションを指定しなかった場合、プロジェクトのルートのREADME.mdがドキュメントのディレクトリーにそのままコピーされたうえで、目次ページを含むほかのページが自動生成されます。

README.mdの代わりに別のファイルをコピーしたい場合は、そのファイルへのパスを指定します。パスの代わりにnoneを指定した場合は、目次ページが[ドキュメントのディレクトリー]/README.mdとして生成されます。

ドキュメントに記載するプロジェクトの名前を指定します。デフォルトではpackage.jsonのnameの値が使用されます。package.jsonのnameとプロジェクトの正式名称が異なる場合に便利です。

この記事では、TypeScriptのJSDocからMarkdown形式でドキュメントを自動生成する方法を解説しました。この方法は、ソースコードにJSDocコメントを記述するだけで、見やすく整理されたドキュメントを作成できるというメリットがあります。

一方で、ドキュメントにサンプルコードを載せたい場合はJSDocの@exampleを使ってソースコード内に記述する必要があり、コメントが冗長になります。

これらの点を踏まえたうえで、ぜひTypeScriptプロジェクトへの導入を検討してみてください。