Typedoc starting with Angular project
Angular プロジェクトで始めるtypedoc
きっかけ / Trigger
日常の業務で、プログラム仕様書を作成する時間を効率良く確保するために typedocの導入を決めました
導入 / Introduction
事前準備環境
今回のバージョンは、下記の通りです。
- node v10.14.1
- npm v6.5.0
- Angular CLI v6.0.0
- typescript ~v2.7.2
- typedoc ~v0.12.0
公開手順 / Publication procedure
今回のバージョンは、下記の通りです。
- angular プロジェクトの作成 / create angular project
- typedoc のインストール / typedoc installation
- typedoc.json 実装 / typedoc.json implementation
- typedoc スクリプト実装 / typedoc script implementation
- typedoc コメント実装 / typedoc comment implementation
- typedoc 生成 / typedoc generate
- Github へ push / push to Github
- Github Page の設定 / Github Page Settings
angular プロジェクトの作成 / create angular project
下記コマンドでプロジェクトを作成します / Create a project with the following command
➜ $ ng new typedoc-sample --style=scss // スタイルシートは、scss
typedoc のインストール / typedoc installation
下記コマンドでtypedocをインストールします / Install typedoc with the following command
➜ $ npm install –save-dev typedoc
typedoc.jsonを下記内容で作成します / Create typedoc.json with the following contents
{
"mode": "modules",
"out": "docs", <== ドキュメント出力フォルダ
"theme": "default",
"ignoreCompilerErrors": "true",
"experimentalDecorators": "true",
"emitDecoratorMetadata": "true",
"target": "ES5",
"moduleResolution": "node",
"preserveConstEnums": "true",
"stripInternal": "true",
"suppressExcessPropertyErrors": "true",
"suppressImplicitAnyIndexErrors": "true",
"module": "commonjs"
}
typedoc スクリプト実装 / typedoc script implementation
package.jsonに下記内容のスクリプトに追記します / Add the script below to package.json 参考: https://typedoc.org/api/
"docs": "npm run typedoc -- --options typedoc.json --mode file --exclude '**/*.spec.ts' ./src/",
"typedoc": "typedoc",
typedoc コメント実装 / typedoc comment implementation
typedocフォーマットを関数に記載します / Describe typedoc format in function
参考: https://typedoc.org/api/
/**
* 関数の説明
* @param path ダミー引数
* @return ダミー戻り値
*/
sampleMethod(path: string): string {
return path;
}
typedoc 生成 / typedoc generate
typedoc を生成します / generate typedoc
$ npm run docs
> typedoc-sample@0.0.0 docs
> npm run typedoc -- --options typedoc.json --mode file --exclude '**/*.spec.ts' ./src/
> typedoc-sample@0.0.0 typedoc /work/typedoc-sample
> typedoc "--options" "typedoc.json" "--mode" "file" "--exclude" "**/*.spec.ts" "./src/"
Using TypeScript 3.0.1 from /typedoc-sample/node_modules/typedoc/node_modules/typescript/lib
Rendering [========================================] 100% Documentation
generated at /typedoc-sample/docs
公開結果 / Public results
公開ページ / Public Page
生成ドキュメント / Generated document
