ざきの学習帳

日々の学びを書きます

【Vue.js】 @vuese/cli でコンポーネント一覧のドキュメントをサクっと生成・プレビューする

Vue.js プログラミング

f:id:kic-yuuki:20191217135709p:plain

Vue Advent Calendar 2019 17日目の記事です。


16日目はgyarasuさんでした、お疲れ様でした！👏

この記事では@vuese/cli について、
導入までの手順を調査した際のメモを記載したいと思います。

@vuese/cli とは？ 🤔

Vue.jsのドキュメント生成・プレビューできるライブラリです。

ざっくり、以下のようなことをしてくれます。

  • *.vueから props / slot / emit 等、コンポーネントとして参照する対象情報を走査
    • Markdown形式のファイルに出力（ソースのコメント文を拾って説明やグルーピングしてくれる）
    • プレビュー機能がある

業務でも導入してみたのですが、

  • さくっとコンポーネント一覧を出力したい
  • 新規参画者も整備しやすいドキュメントを作りたい

のようなことを考えているチーム・プロジェクトには、
うってつけなライブラリと思いました。

プレビューのイメージは以下になります。

f:id:kic-yuuki:20191217131723p:plain

導入手順

以下ドキュメントを参考に、
リポジトリ・PRをベースに導入した手順を記載していきます。

インストール・設定

@vuese/cliをイントールします。

npm i -D @vuese/cli
# yarn add -D @vuese/cli

ドキュメント生成→プレビューを1コマンドで済ませるよう、
以下のnpm-scriptsを追記します。

// package.json
{
  "scripts": {
    "doc:gen": "rm -rf website && npx vuese gen",
    "doc:serve": "vuese serve --open",
    "doc": "npm run doc:gen && npm run doc:serve"
  }
}

@vuese/cliは、デフォルト/website配下にMarkdownを出力します。
コミット対象外としたい場合、.gitignoreにwebsite/を追記しておきます。

# .gitignore
website/
  • ドキュメント生成対象の*.vueファイル
  • 出力ディレクトリの指定

といった設定情報は、以下ドキュメントを参考に.vuesercへ記載します。

例として、ドキュメントプレビュー表示時のタイトルを設定する場合は、
以下のように記載します。

// .vueserc
{
  "title": "コンポーネント一覧"
}

*.vueファイルに説明をコメントで記載

上記をもとにコンポーネントやprops等の説明をコメント文で設定します。

以下には、個人的に重要と思った内容を抜粋して記載します。

グルーピング

プレビューする際、
以下赤枠のようにコンポーネントをグルーピングできます。

f:id:kic-yuuki:20191217134940p:plain

グルーピングは、以下ソースのように、
*.vueに @groupアノテーションを設定します。

// vue-material-v1-sandbox/src/components/global/SideNav.vue
/**
 * 〜省略〜
 * @group global
 * サイドバー
 */
export default {
  // 〜省略〜
}
</script>

【注意】ドキュメント生成されない*.vueファイルがある

@vuese/cli - Precautionsにも記載されている通り、
props / slot / emit などの情報を含まない*.vueファイルは、
デフォルト、ドキュメント生成対象外となります。

生成対象とするには、以下ソースのように

を設定する必要があります。

// vue-material-v1-sandbox/src/components/pages/MdFieldTest.vue
<script>
/**
 * @vuese
 * 〜省略〜
 * `vue-material` の `md-field` 系お試しページ
 */
export default {
  name: 'MdFieldTest',
  // 〜省略〜
}
</script>

プレビューすると、説明文のみが表示されます。

f:id:kic-yuuki:20191217131831p:plain

おまけ

@vuese/cliでは、methodsもデフォルト出力しません。

しかし、$refs経由でコンポーネントのメソッドを呼びたいケースを想定すると、
ドキュメント出力したくなるケースもあります。

methodsをドキュメント生成対象とするには、
先ほど説明した@vueseアノテーションを設定します。

ドキュメント生成→プレビュー

ドキュメント生成→プレビューするため、
あらかじめ設定したnpm-scriptsを実行します。

npm run doc
# rm -rf website && npx vuese gen && npx vuese serve --open でも同様

f:id:kic-yuuki:20191217131723p:plain

サイドバーのグルーピング、記載した説明が表示されていることを確認できます。 上記のように表示できたら、動作確認OKです。

おわり

以上になります。

もし気になる点などありましたら、フィードバックいただけると助かります。🙏

参考文献

公式のドキュメントやvueseに関する紹介記事がほかにもありましたので、
合わせて参考にしていただければと思います。