Last updated at
Storybook の公式アドオンである Addon Docs は、5.3 から Vue(や Angular や Web Components)におけるコンポーネントドキュメントの自動生成機能がサポートされるようになりました。 これは、コンポーネントを指定するだけでその Props や Events, Slots の型やコメントがドキュメントとして生成できる、というものです。
この記事では、如何にして Vue 版のドキュメントが自動生成されているのか、またその仕組みを Storybook 以外で使うことについて説明します。
ドキュメントを自動生成するには、まずどうにかしてコンポーネントの(Props 等)を取得、またそれらに対して書かれたコメントを抽出する必要があります(メタ情報の抽出)。
この工程をまるっと行ってくれるのが、Vue Styleguidist※1というプロジェクトのvue-docgen-api
というライブラリです。
vue-docgen-api
はコンポーネントファイルを読み込み、その内容を解析して JSON として出力してくれます。
<!-- Foo.vue -->
<template>
<div>
<!-- @slot my slot -->
<slot />
</div>
</template>
<script>
/**
* I'm Foo!
*/
export default {
props: {
/**
* Foo the Bar.
*/
foo: {
type: String
}
}
}
</script>
こんなコンポーネントから、
{
"description": "I'm Foo!",
"props": [
{
"description": "Foo the Bar.",
"name": "foo",
"type": {
"name": "string"
}
}
],
"slots": [
{
"description": "my slot"
}
]
}
こんな感じのメタ情報を生成してくれます。(色々省略しています)
※1 ... Storybook と同じようなコンポーネントカタログツール。どちらかというとドキュメントの部分に重きを置いている。
vue-docgen-api
によって抽出されたメタ情報はvue-docgen-loader
という webpack のローダーによって、コンポーネントオブジェクトにこっそり追加されます。
import Foo from 'Foo.vue'
console.dir(Foo.__docgenInfo) // メタ情報がそのまま詰まっている
そして Docs Addon はこのコンポーネントにひっついているメタ情報を元に、Props や Events, Slots のテーブルをレンダリングする、というわけです。
前述したようにメタ情報はvue-docgen-api
によって生成されvue-docgen-loader
によってコンポーネントに注入されます。
つまり、この一連のプロセスには一切 Storybook 関連のものが入っていないということになります。
そのため、webpack 環境さえあればFoo.__docgenInfo
でメタ情報を抽出できる環境を構築することができます。
具体的にどんな用途に使えるのかは人やプロジェクトによって異なりますが、例えばスクラッチでドキュメントを作成する際にコンポーネントのメタ情報を自動生成する、というようなことが可能になります(サンプル)。
vue-docgen-loader
は名前の通り webpack のローダーなのでやりたい放題できてしまいます。
しかし、コンパイルにかかる時間やバンドルサイズを考えると、あくまでもドキュメンテーションのようなメインのアプリケーション以外にのみ利用することを推奨します。