每个开发者都想读好文档,每个开发者都想写好文档,实际上只有少数开发者可以这样做,让我们来看看一个非常简单的方法,既可以为您的 Vue.js 组件生成文档,也可以使用 propdoc来渲染它。
安装
像任何其他 Vue 插件一样安装 propdoc:通过 Yarn 或 NPM。
1# Yarn
2$ yarn add propdoc
3
4# NPM
5$ npm install propdoc --save
文件组件
propdoc的最大特点是能够在组件上写你的文档作为属性。这些只有在你使用propdoc来渲染文档时才会使用。否则他们没有效果。
1[label MyButton.vue]
2<template>
3 <div class="my-button" :class="{
4 flat: isFlat,
5 raised: isRaised,
6 primary: isPrimary
7 }">
8 <slot></slot>
9 </div>
10</template>
11
12<script>
13
14export default {
15 name: "my-button",
16 introduction: "A basic example button.",
17 description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
18 token: `<my-button isFlat isPrimary>Button Text</my-button>`,
19
20 props: {
21 isFlat: {
22 type: Boolean,
23 default: false,
24 note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
25 },
26
27 isRaised: {
28 type: Boolean,
29 default: true,
30 note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
31 },
32
33 isPrimary: {
34 type: Boolean,
35 default: false,
36 note: 'Whether or not to use the primary coloring.'
37 }
38 }
39}
40
41</script>
除了通常的内置密钥,如名称和组件和附件所需的密钥,propdoc 还添加了一些:
- note: 告诉你什么是 prop
- introduction: 对组件的快速介绍
- description: 对组件的详细描述. 支持 Markdown
- token: 显示如何使用组件的代码。
提供文档
对您的组件的文档也非常方便,只需添加propDoc组件,并在组件支持器中传递您的文档组件。
1[label DocumentationComponent.vue]
2<template>
3 <div>
4 <!-- Render the documentation for MyButton -->
5 <prop-doc :component="MyButton"></prop-doc>
6 </div>
7</template>
8
9<script>
10import propDoc from 'propdoc';
11import MyButton from './MyButton.vue';
12
13export default {
14 components: {
15 propDoc
16 },
17
18 data() {
19 return {
20 MyButton
21 }
22 }
23}
24</script>