TypeDocをGitHub Actions・GitHub Pagesで使ってTypeScriptのドキュメントを作成する

TypeDoc TypeScript TSDoc GitHub Actions Github Pages

はじめに

TypeScriptのモジュールを作っているので、せっかくなのでTypeDocでAPIリファレンスを作成してみた。

この記事の前半ではTypeDocについて軽くまとめた（タグについては個人的に早見表が欲しかったので作成してみた）。
後半ではGitHub ActionsとGitHub Pagesを使ってGitHubへソースコードをプッシュした際に自動的にAPIリファレンスを公開する方法を記載しておく。

TypeDocについて

TypeDocについてざっくり理解するため、以下の公式サイトのドキュメントをまとめた。

Doc Comments | TypeDoc

変換、記法

Markdown記法が使える
コードブロックが使える
コードへの参照リンクを作成できる

Markdown記法が使える

コメントにMarkdown記法を利用することができ、HTMLに変換される。
Markdownの変換にはMarkedが使われているので、細かい記法などはそれを参照すればよいのだろう。

例：supoortsが斜体になり、Markdownというリンクに変換される

/**
 * This comment _supports_ [Markdown](https://marked.js.org/)
 */
export class DocumentMe {}

コードブロックが使える

コメントにサンプルコード等を記載することができる。
シンタックスハイライトにはShikiが使われている。

例

/**
 * Code blocks are great for examples
 *
 * ```typescript
 * // run typedoc --help for a list of supported languages
 * const instance = new MyClass();
 * ```
 */
export class MyClass {}

コードへの参照リンクを作成できる

コメント内で他のクラスや他のクラスのプロパティへのリンクを貼りたいときに利用する。
TypeDocではDeclaration Referencesと表現されている。

モジュールを参照するときの区切り文字やらなんやら細かく決まっているので、リンク先にて詳細は確認してコメントを記述する。

サポートしているタグの早見表

TypeDoc	使い方	TSDoc
@alpha	タグがつけられているメソッドなどはまだ安定していない。アルファ版の意味。	@alpha
@beta	タグがつけられているメソッドなどはまだ安定していない。ベータ版の意味。	@beta
@category	いくつかのAPIをまとめるためのタグ	-
@defaultValue	非必須のプロパティに値が与えられなかったときの扱い	@defaultValue
@deprecated	非推奨のメソッドなど。将来的に削除される。	@deprecated
@enum	文字列または数値のオブジェクトをEnumとして扱う。TypeScriptのEnumではない。	-
@event	"Events"というグループにまとめるためのタグ。EventEmitterなどの実装でイベント名につけておく。（`@group Events`と同義）	-
@eventProperty	"Events"というグループにまとめるためのタグ。EventEmitterなどの実装でイベント名につけておく。（`@group Events`と同義）	@eventProperty
@example	関数の使い方を書くためのタグ	@example
@experimental	タグがつけられているメソッドなどはまだ安定していない。実験版の意味。`@beta`と同じ。	@experimental
@group	APIをグループ化するためのタグ	-
@hidden	ドキュメントに表示させなくするためのタグ。`@ignore`と同じ。	-
@ignore	ドキュメントに表示させなくするためのタグ。`@ignore`と同じ。	-
{@inheritDoc}	他の注釈をコピーして表示させるためのタグ。コピー元の指定方法はDeclaration References参照。	@inheritDoc
@internal	モジュール内部で使うメソッドなどにつけるタグ。	@internal
{@label}	他のタグ（`{@link}`など）からの指定に利用できるラベル名をつけるためのタグ。	@label
{@link}	別のドキュメントへのリンクを作成するタグ。	@link
@module	パッケージ全体に対するコメントを書くタグ。`@packageDocumentation`と同じ。	-
@override	クラスを使ったとき、オーバーライドしたメソッドにつけるタグ。	@override
@packageDocumentation	パッケージ全体に対するコメントを書くタグ。`@module`と同じ。	@packageDocumentation
@param	関数またはメソッドの引数を書くためのタグ。	@param
@private	可視性を示すためのタグ。可視性を設定する`private`を使えばよいので、このタグは一般的に利用すべきでなく、将来のリリースで削除される。	-
@privateRemarks	公開しないドキュメントにつけるタグ。	@privateRemarks
@protected	可視性を示すためのタグ。可視性を設定する`protected`を使えばよいので、このタグは一般的に利用すべきでなく、将来のリリースで削除される。	-
@public	このタグがついているメソッドなどが正式版になったことを示す。	@public
@readonly	読み取り専用のAPIであることを示すタグ。	@readonly
@remarks	備考を書き込むためのタグ。このタグよりも上は要約と解釈される。	@remarks
@returns	戻り値を書くためのタグ。	@returns
@sealed	このタグがクラスについていれば、継承してはならないことを示し、メソッドについていればオーバーライドしてはいけないことを示す。	@sealed
@see	このタグがついているAPIに関連する情報を示す。ハイパーリンクをつくる場合には、`{@link}`が推奨される。	@see
@template	型情報を記載するためのタグ。`@typeParam`のエイリアス。	-
@throws	関数やメソッドからスローされうる例外を書くためのタグ。	@throws
@typeParam	型情報を記載するためのタグ。	@typeParam
@virtual	このタグがついている関数、プロパティはサブクラスでオーバーライドされることを示す。	@virtual

カスタムテーマ

APIリファレンスにはカスタムテーマがいくつか存在している。
見た目がいい感じになるものから、階層やカテゴリごとに並べるなどの機能的なものまである。

Themes | TypeDoc

GitHub ActionsとGitHub Pagesを使ったAPIリファレンスの自動公開

TypeDocの設定

npmからtypedocをインストールする。
使いたければ他にドキュメント用のカスタムテーマもインストールする。今回は、ソースコードの階層構造に従って表示してくれる@youlin/typedoc-theme-hierarchyをインストールする。

npmスクリプトを以下のように設定しておく。
これでnpm run docと打つことでdocsフォルダにAPIリファレンスを出力してくれるようになる。

"doc": "typedoc --entryPoints src --entryPointStrategy expand --out ./docs --plugin ./node_modules/@youlin/typedoc-theme-hierarchy/dist/index.js --theme hierarchy",

GitHub Actionsの設定

GitHub ActionsではGitHub Pagesで公開する設定をymlでおこなう。
内部ではpeaceiris/actions-gh-pagesというActionsを使っている（参考：GitHub Actions による GitHub Pages への自動デプロイ - Qiita）。

.github/workflows/gh-pages.ymlを以下のように編集し、mainブランチにプッシュされたときにこのActionsが実行されるようにする。

name: GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/[email protected]
      - uses: actions/[email protected]
        with:
          node-version: 14

      - name: Install
        run: npm install

      - name: Build
        run: npm run doc

      - name: Deploy
        uses: peaceiris/[email protected]
        with:
          github_token: ${{ secrets.GITHUB\_TOKEN }}
          publish_dir: ./docs