TypeScriptのモジュールを作っているので、せっかくなのでTypeDocでAPIリファレンスを作成してみた。
この記事の前半ではTypeDocについて軽くまとめた(タグについては個人的に早見表が欲しかったので作成してみた)。
後半ではGitHub ActionsとGitHub Pagesを使ってGitHubへソースコードをプッシュした際に自動的にAPIリファレンスを公開する方法を記載しておく。
TypeDocについてざっくり理解するため、以下の公式サイトのドキュメントをまとめた。
コメントに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リファレンスにはカスタムテーマがいくつか存在している。
見た目がいい感じになるものから、階層やカテゴリごとに並べるなどの機能的なものまである。
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 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
Crieitは誰でも投稿できるサービスです。 是非記事の投稿をお願いします。どんな軽い内容でも投稿できます。
また、「こんな記事が読みたいけど見つからない!」という方は是非記事投稿リクエストボードへ!
こじんまりと作業ログやメモ、進捗を書き残しておきたい方はボード機能をご利用ください。
ボードとは?
コメント