Vue Advent Calendar 2019 17日目の記事です。
16日目はgyarasuさんでした、お疲れ様でした！👏
- 16日目の記事 - Vue.jsプラグインで始めるOSS - Qiita
この記事では@vuese/cli について、
導入までの手順を調査した際のメモを記載したいと思います。
@vuese/cli とは？ 🤔
Vue.jsのドキュメント生成・プレビューできるライブラリです。
ざっくり、以下のようなことをしてくれます。
*.vueからprops/slot/emit等、コンポーネントとして参照する対象情報を走査
業務でも導入してみたのですが、
- さくっとコンポーネント一覧を出力したい
- 新規参画者も整備しやすいドキュメントを作りたい
のようなことを考えているチーム・プロジェクトには、
うってつけなライブラリと思いました。
プレビューのイメージは以下になります。
導入手順
以下ドキュメントを参考に、
リポジトリ・PRをベースに導入した手順を記載していきます。
- ドキュメント
- 導入した際のGitHub情報
インストール・設定
@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等の説明をコメント文で設定します。
以下には、個人的に重要と思った内容を抜粋して記載します。
グルーピング
プレビューする際、
以下赤枠のようにコンポーネントをグルーピングできます。
グルーピングは、以下ソースのように、
*.vueに @groupアノテーションを設定します。
// vue-material-v1-sandbox/src/components/global/SideNav.vue
/**
* 〜省略〜
* @group global
* サイドバー
*/
export default {
// 〜省略〜
}
</script>
【注意】ドキュメント生成されない*.vueファイルがある
@vuese/cli - Precautionsにも記載されている通り、
props / slot / emit などの情報を含まない*.vueファイルは、
デフォルト、ドキュメント生成対象外となります。
生成対象とするには、以下ソースのように
@vueseのアノテーションname属性
を設定する必要があります。
// vue-material-v1-sandbox/src/components/pages/MdFieldTest.vue <script> /** * @vuese * 〜省略〜 * `vue-material` の `md-field` 系お試しページ */ export default { name: 'MdFieldTest', // 〜省略〜 } </script>
プレビューすると、説明文のみが表示されます。
おまけ
@vuese/cliでは、methodsもデフォルト出力しません。
しかし、$refs経由でコンポーネントのメソッドを呼びたいケースを想定すると、
ドキュメント出力したくなるケースもあります。
methodsをドキュメント生成対象とするには、
先ほど説明した@vueseアノテーションを設定します。
ドキュメント生成→プレビュー
ドキュメント生成→プレビューするため、
あらかじめ設定したnpm-scriptsを実行します。
npm run doc # rm -rf website && npx vuese gen && npx vuese serve --open でも同様
サイドバーのグルーピング、記載した説明が表示されていることを確認できます。 上記のように表示できたら、動作確認OKです。
おわり
以上になります。
もし気になる点などありましたら、フィードバックいただけると助かります。🙏
参考文献
公式のドキュメントやvueseに関する紹介記事がほかにもありましたので、
合わせて参考にしていただければと思います。
