APIドキュメントしたい（`typedoc`）

$ npx typedoc

TypeDocは、TypeScriptのソースコードに書かれたコメントを使ってAPIドキュメントを生成するツールです。 TSDoc形式とJSDoc形式に対応しています。デフォルトではHTML形式のドキュメントが生成され、これだけでブラウザで閲覧できるAPIリファレンスとして完結します。

注釈

TSDoc形式はTypeScriptの中にドキュメントを記述するための標準的な仕様です。 Microsoftが中心となって開発し、現在はオープンソースとして管理されています。

TypeScript自体の標準機能ではないですが、 TypeDocと組み合わせてAPIドキュメントを生成するのが、デファクトスタンダードになっています。

インストールしたい（`typedoc`）

$ npm install --save-dev typedoc

typedocパッケージをdevDependenciesとして追加します。

スクリプト設定したい（`package.json`）

{
    "name": "...",
    "scripts": {
        "docs:api": "typedoc",
        "...": "..."
    }
}

$ npm run docs:api

npm scriptsにdocs:apiを登録しておくと、 npx typedocを直接打たなくてもnpm run docs:apiだけで実行できます。他のビルドタスク（buildやbundle）と並べて管理しやすくなります。

設定したい（`typedoc.json`）

{
    "entryPoints": ["src/index.ts"],
    "out": "docs/api",
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true,
    "excludeInternal": true
}

設定ファイルはtypedoc.jsonです。エントリーポイント（entryPoints）と出力先（out）を指定すればOKです。

excludePrivate・excludeProtected・excludeExternals・excludeInternalは、外部に公開したくないメンバー（private/protectedや@internalが付いたもの）を出力から除外するオプションです。公開APIだけをドキュメント化したい場合に指定します。

その他のオプションはお好みで設定してください。

ホットリロードしたい

$ npx typedoc --watch

--watchオプションでホットリロードできます。ドキュメントを整理しているときに、自動で再生成してくれるので便利です。

Markdownで出力したい（`typedoc-plugin-markdown`）

ここから先はオプションです。 TypeDoc単体で完結させたい場合は、ここまでの設定で十分です。

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

{
    "entryPoints": ["src/index.ts"],
    "out": "docs/api",
    "plugin": ["typedoc-plugin-markdown"],
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true,
    "excludeInternal": true,
    "disableSources": true,
    "readme": "none",
    "hideBreadcrumbs": true,
    "hideGenerator": true
}

TypeDocが生成するファイルはデフォルトでHTML形式ですが、 pluginにtypedoc-plugin-markdownを追加すると、Markdown形式で生成できます。

disableSourcesは、各項目にソースファイルへのリンクを付けないオプションです。 hideGeneratorは、生成されたページ末尾のTypeDocへのリンクを非表示にします。どちらも、他のツールで作ったドキュメントサイトに違和感なく溶け込ませたいときに便利です。

ヒント

Markdown形式で出力しておくと、Sphinx（本サイト）やMkDocs、 Python製のZensicalのような、 TypeScript以外のドキュメントツールにもそのまま取り込めます。 API部分だけTypeDocに任せ、それ以外のドキュメント本体は好きなツールで書く、という構成にできます。

ドキュメントサイトに組み込みたい

typedoc-plugin-markdownで出力すると、 outで指定したディレクトリ（例：docs/api/）に README.md（インデックス）と、 classes/・functions/・type-aliases/などのサブディレクトリが生成されます。

$ npx typedoc
$ ls docs/api
README.md  classes/  functions/  interfaces/  type-aliases/  variables/

あとは、Sphinx（本サイト）やMkDocs、Zensicalなど、使っているドキュメントツールのナビゲーション設定に docs/api/README.mdを登録すれば、 TypeDocが生成したAPIリファレンスをドキュメントサイトの一部として組み込めます。

ヒント

outをドキュメントツールのソースディレクトリ配下（例：docs/api）に指定しておくと、 npx typedocを実行するだけでドキュメントサイトのビルド対象にそのまま含められます。

APIドキュメントしたい（typedoc）

インストールしたい（typedoc）

スクリプト設定したい（package.json）

設定したい（typedoc.json）