はじめに
TypeScriptのモジュールを作っているので、せっかくなのでTypeDocでAPIリファレンスを作成してみた。
この記事の前半ではTypeDocについて軽くまとめた(タグについては個人的に早見表が欲しかったので作成してみた)。 後半ではGitHub ActionsとGitHub Pagesを使ってGitHubへソースコードをプッシュした際に自動的にAPIリファレンスを公開する方法を記載しておく。
TypeDocについて
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リファレンスにはカスタムテーマがいくつか存在している。 見た目がいい感じになるものから、階層やカテゴリごとに並べるなどの機能的なものまである。
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/checkout@v3 - uses: actions/setup-node@v3 with: node-version: 14 - name: Install run: npm install - name: Build run: npm run doc - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB\_TOKEN }} publish_dir: ./docs
参考文献
- 公式サイト:TypeDoc
- カスタムテーマ:@youlin/typedoc-theme-hierarchy - npm
- TypeScriptのリファレンスドキュメント生成にtypedocが便利だった - オフトゥン大好き。
- GitHub Actions による GitHub Pages への自動デプロイ - Qiita
- peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.