Storybook for VueのDocs Addonの裏側: コンポーネントの自動ドキュメント生成について

はじめに

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 のテーブルをレンダリングする、というわけです。

Storybook 以外でメタ情報を使う

前述したようにメタ情報はvue-docgen-apiによって生成されvue-docgen-loaderによってコンポーネントに注入されます。 つまり、この一連のプロセスには一切 Storybook 関連のものが入っていないということになります。 そのため、webpack 環境さえあればFoo.__docgenInfoでメタ情報を抽出できる環境を構築することができます。

具体的にどんな用途に使えるのかは人やプロジェクトによって異なりますが、例えばスクラッチでドキュメントを作成する際にコンポーネントのメタ情報を自動生成する、というようなことが可能になります(サンプル)。

注意点

vue-docgen-loaderは名前の通り webpack のローダーなのでやりたい放題できてしまいます。 しかし、コンパイルにかかる時間やバンドルサイズを考えると、あくまでもドキュメンテーションのようなメインのアプリケーション以外にのみ利用することを推奨します。