TypeScript: API-Extractor(tsdoc) で markdown を生成し、それを Word に変換して簡易仕様書へ

背景

TypeScript でコメントを元に Word か PDF を生成して仕様書にしようとした際の記録

今回は tag 拡張もしないし、Word も適当でよいので設定も変換したら OK ってとこがゴール

環境

• windows 10
• node.js v18.11.0
  • nvm 1.1.10
  • npm 8.19.2
• office(word): *.docx 出力用

結論

1. API-Extractor(tsdoc) + API-Documenter で markdown を生成

   • マークダウンはこんな感じ
     

2. pandoc で markdown ファイル群を結合して Word を生成

   • Word イメージ
     

詳細

API-Extractor(tsdoc) + API-Documenter で markdown を生成

まずは API-Extractor で API Model の生成後、
API-Documenter で markdown 生成まで

Api-Extractor (tsdoc)

API-Extractor をインストールして初期化と設定

まずはインストール

install

npm install -g @microsoft/api-extractor

初期化して、api-extractor.json を生成

init して、api-extractor.json を生成

api-extractor init

api-extractor.json の最低限の設定は、"mainEntryPointFilePath"
tsconfig.json での outDir を元に設定すればよいかと。

api-extractor.json の変更点

  "mainEntryPointFilePath": "<projectFolder>/built/index.d.ts",

上記の例では、tsconfig.json で以下のように設定してる為

tsconfig.json

"outDir": "./built/",      /* Specify an output folder for all emitted files. */

tsconfig の設定変更

Model 解析をする為に必要な *.d.ts の生成をする為に以下を有効化

設定変更

    "composite": true,　　// declarationMap に必要
    "declaration": true
    "declarationMap": true

変更後に、tsc で build が必要

tsc

Build しないと、設定変更だけなので、以下のようにエラーが出る筈

The "mainEntryPointFilePath" path does not exist:

モデルの生成前準備

apiReport の出力先変更

api-extractor.json 変更結果はこんな感じ。コメント外して、json エラーを解除（"," 追加）した程度

  "apiReport": {
    "enabled": true,
    "reportFileName": "<unscopedPackageName>.api.md",
    "reportFolder": "<projectFolder>/temp/",
    "reportTempFolder": "<projectFolder>/temp/",
  },

コメント内の default の出力先は <temp> としてるが、間違っていて、実際は <etc> になっている。

故に、上記をしないと、以下エラーが出ます。

Error: Unable to create the API report file. Please make sure the target folder exists:

回避策として、以下でもOKかと
<projectFolder>/etc フォルダを生成

で、ようやくAPI Model を生成

*.api.json を生成

API モデルを生成

api-extractor run --local --verbose

この時点で、以下が生成されていれば OK

api-documenter

api-documenter のインストール

api-documenter のインストール

npm install -g @microsoft/api-documenter

api-documenter での markdown 生成

markdown 生成

api-documenter markdown -i ./temp   

入力フォルダ(-i) ./temp は api-extractor.json 設定次第

最終的な markdown の出力例はこんな感じ

pandoc で markdown ファイル群を結合して Word を生成

まずは install

ダウンロードは以下から最新版を

pandoc で出力

面倒なので、power shell ファイルを用意して

./createWord.ps1

みたいな感じで生成する

createdWord.ps1

Set-Location ./doc/markdown

# markdown ファイルの一覧
$inputs = Get-ChildItem ./ -Recurse -Name -include *.md | Sort-Object -Descending
# ファイル名: 拡張子で勝手に出力内容を変えてくれる。但し、対応機能のインストールは必要な可能性有。-f/-t は削除した場合
$output = "../word/Specifications.docx"

# 以下 {user} を自身の user へ
C:\Users\{user}\AppData\Local\Pandoc\pandoc.exe `
  --toc `
  -f markdown `
  -N $inputs `
  -t docx `
  -o $output

Set-Location ../../

# --reference-doc=*.odt # *.odt を提供することで好みのスタイルへ

概要としては以下

1. *.md フォルダに移動
2. ファイル一覧取得
3. -N オプションで渡して -o で出力フォルダを渡す
4. pandoc を呼び出して、markdown to word を実行
5. フォルダを元に戻す

こんな感じで出力されれば完成

pandoc についてはいろいろ情報があるので、割愛

ちょっとした tips

package.json の scripts 設定例

こんな感じで設定して、設定して、npm run apidoc ってやれば、build して markdown が生成される筈

package.json への追加

"scripts": {
    "preapidoc": "tsc --build",
    "apidoc": "api-extractor run --local --verbose && api-documenter markdown -i ./temp -o ./doc/markdown",
}

npm run apidoc の前後に何かを作業するって便利

package.json 内の scripts に pre{script name}, post{script name} を記述する。
詳細は以下。実例は上述

複数の package をまとめる

api-documenter の input フォルダに *.api.json/md を並べておけば、全部まとめて markdown にして package 一覧に入れてくれる。

こんな感じ

api-extractor では markdown/yaml が生成可能

pandoc で pdf や HTML 等出力可能

参照

コードからモデルを生成

定義

pandoc

あとがき

当初は jsdoc を試してて、途中で typedoc に気付いて試行してたけど、
結局 tsdoc を利用したくて api-extractor にしました。

決めては、TypeScript を生み出した Microsoft が推してるってところ。

以下の記事にあるように、自分も JavaScript は苦手だったけど、やってみたら C# が好きだった感覚と似てた

この辺とかにも

C# と同様、TypeScript には にジェネリックやラムダ式 (またはそれらに等価なもの) があります。

typedoc もよかったんだけどねぇ

typedoc もいいよね

使いやすいし、検索窓がめっちゃ便利なので、HTML で良い時に使いたい