Propdocを使用してVue.jsコンポーネントを文書化する
すべての開発者は、優れたドキュメントを読みたいと思っています。 すべての開発者は、優れたドキュメントを作成したいと考えています。 実際に行う開発者はほとんどいません。 Vue.jsコンポーネントのドキュメントを生成し、propdocを使用してレンダリングする非常に簡単な方法を見てみましょう。
インストール
他のVueプラグインと同じようにpropdocをインストールします:YarnまたはNPMを介して。
# Yarn
$ yarn add propdoc
# NPM
$ npm install propdoc --save
コンポーネントの文書化
propdoc の最大の機能は、コンポーネントのプロパティとしてドキュメントを作成できることです。 これらは、propdocを使用してドキュメントをレンダリングする場合にのみ使用されます。 それ以外の場合は効果がありません。 驚いたのは、これまでに行われたことがないような天才的なアイデアです。
MyButton.vue
<template>
<div class="my-button" :class="{
flat: isFlat,
raised: isRaised,
primary: isPrimary
}">
<slot></slot>
</div>
</template>
<script>
export default {
name: "my-button",
introduction: "A basic example button.",
description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
token: `<my-button isFlat isPrimary>Button Text</my-button>`,
props: {
isFlat: {
type: Boolean,
default: false,
note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
},
isRaised: {
type: Boolean,
default: true,
note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
},
isPrimary: {
type: Boolean,
default: false,
note: 'Whether or not to use the primary coloring.'
}
}
}
</script>
コンポーネントと小道具にnameやrequiredなどの通常の組み込みキーに加えて、propdocはさらにいくつか追加します。
- note :小道具が何をするかを伝えます。
- はじめに:コンポーネントの簡単な紹介。
- description :コンポーネントの詳細な説明。 マークダウンをサポートします。
- token :コンポーネントの使用方法を示すちょっとしたコード。
レンダリングドキュメント
コンポーネントのドキュメントも簡単に作成できます。 propDoc コンポーネントを追加し、ドキュメント化されたコンポーネントをcomponentpropで渡します。
DocumentationComponent.vue
<template>
<div>
<!-- Render the documentation for MyButton -->
<prop-doc :component="MyButton"></prop-doc>
</div>
</template>
<script>
import propDoc from 'propdoc';
import MyButton from './MyButton.vue';
export default {
components: {
propDoc
},
data() {
return {
MyButton
}
}
}
</script>