近期新开项目，发现之前编写的组件不知道怎么用，要不看源码，要不就只能看以前的代码。所以找到Vue-styleguidist，把之前的组件都编写文档方便以后使用，就像看element-ui等组件库的文档一样，使大家的开发效率提升，推荐给各位。先上官方 demo 看看效果，多种样式供你选择。
起步
安装
npm安装
npm install --save-dev vue-styleguidist如果使用的是Vue Cli，可以使用其插件
vue add styleguidist配置你的样式风格
创建一个styleguide.config.js文件在package.json同一级目录，这个是你的配置文件，在这个文件里，你可以：
- 指定Styleguidist到你的vue组件文件夹
- 明确如何加载代码
如果使用了Vue cli可以跳过这个步骤。当安装vue-cli-plugin-styleguidist,styleguidist会从cli中获取相关内容，通知styleguidist组件目录
添加npm脚本方便使用
添加这些脚本到package.json:
{
"scripts": {
"styleguide": "vue-styleguidist server",
"styleguide:build": "vue-styleguidist build"
}
}开始styleguidist
- 运行
npm run styleguide启动styleguide开发服务 - 运行
npm run styleguide:build构建一个固定版本
开始编写组件文档
编写组件文档
Vue styleguidist是基于组件源码和Readme文件中的注释声明进行生成组件文档。
代码注释
Vue styleguidist会显示组件中JSDoc注释内容
/* ... */
请注意使用了@displayName标签将该变组件名称，这是一个顶层的注释，必须出现在脚本标签export default之前。
如果组件中创建了自定义的v-model，你必须添加model标签在注释中
在vue组件中，对组件的prop设置限定有效值是很常见的。例如，size只能够接受small，medium和large。这种情况，使用@values标签。
Events
编写事件的文档，在其触发事件的代码上方添加注释。如果不紧邻触发事件的代码，将会被忽略。
在脚本块中
如果事件已经显式明确了，则不需要告诉styleguidist事件名称
/**
* Success event.
*/
this.$emit('success')常量也会被识别出来
/**
* Success event.
*/
const success = 'succ'
this.$emit(success)如果使用的事件名称从对象中取出，则需要使用@event标签
/**
* Success event.
*
* @event success
*/
this.$emit(EVENTS.success)如果时间传入的有参数或属性，使用@propety标签的描述它。也可以使用@arg或者@param。
/**
* Triggers when the number changes
*
* @property {number} newValue new value set
* @property {number} oldValue value that was set before the change
*/
this.$emit('change', newValue, oldValue)在template中
被直接用在v-on表达式中触发的事件将自动被检测到。为了更好地文档说明他们，可以在template中，在$emit被调用的代码行上面添加注释。
注释块内编写文档需要包含一行@event click。剩下的注释块那内容和在脚本中注释一样即可。@property用来描述参数。
插槽slot
styleguidist将自动检测到插槽部分。在插槽前一行添加用@slot注释描述。
除了在给插槽添加描述外，还可以对插槽绑定的属性编写文档。这些属性使用关键字@binding。
格式要求如下：
一个插槽文档的例子：
{{row.item.text}}
包含mixin和extends
如果导入了minxin或extends，也将会被styledist自动添加到你的组件文档中
使用案例和Readme文件
vue styleguidist将在组件的文件夹内查找例如Readme.md或{组件名}.md的文件，将其展示在你的组件文档中作为示例文档。一些使用语言标签vue,js,jsx或者javascript的代码块将被作为vue组件渲染。
如果想忽略组件的readme文件，使用@example [none] doclet。这样也能够解决多个组件在同一个文件夹内共享一个readme文件。这样将防止示例被多次渲染。
Vue component example:One more with generic code fence:
You can disable an editor by passing a
noeditormodifier:To render an example as highlighted source code add a
staticmodifier:You can also initialize vue to construct more complex examples in two ways:
- Create a new Vue instance
const names = require('dog-names').all; new Vue({ data(){ return { list: names } }, template: `` })
- Single-file components with a language tag of vue (supports
Examples with all other languages are rendered only as highlighted source code, not an actual component:
Any Markdown is allowed _here_.
你也可以添加自定义代码块*.vue文件中,这样vue styleguidist也会创建描述文件。
使用注释添加外部示例
使用@example注释，添加外部示例文件。下面这个例子就是加载extra.examples.md文件的示例:
/**
* Component is described here.
*
* @example ./extra.examples.md
*/
export default {
name: 'Button'
// ...
}忽略示例文件
也可以使用@example来忽略关联到readme文件，这样能够防止多次渲染示例文。
/**
* Component is described here.
*
* @example [none]
*/
export default {
name: 'Button'
// ...
}公共方法
默认的组件中methods中的方法被视为私有的，是不会被公开的。可以使用JSDoc中@public标签让方法视为公开，并展示在文档中。
/**
* Insert text at cursor position.
*
* @param {string} text
* @public
*/
insertAtCursor(text) {
// ...
}忽略props
默认情况下，组件中的所有属性props被认为是公开发的。在极少数情况下，想要只在文档中的移除部分属性说明。为此，可以使用JSDoc的@ignore标签注释在属性前面，用于标记在文档中移除它。
props: {
/**
* @ignore
*/
color: {
type: String,
default: '#333'
}使用JSDoc标签
在编写组件、属性或方法文档时，可以使用以下JSDoc标签
@deprecated-
@see，link @author@since@version
displayName
除上面这些标签以外，可以使用@displayName来该变组件在你的文档中显示的名称。但是看到他的名称被修改后，你在调用使用时，也需要使用被命名的名称，名称中的空格和符号在使用时不需要。举个例子，如果展示的名称被修改：
/**
* @displayName Wonderful Button
**/要在示例中引用它时，就需要使用
方法的注释
当编写方法的文档时，你可以使用：
-
@param，@arg，@argument @event@public
组合组件
列表组件或者表格组件常常需要写成一个组合的api。例如，一个下拉菜单可读性强的编写方法是
value 1
value 2
要优于使用属性
vue styleguidist提供编写这种情况的方式：在主组件中添加@require。现在这个下拉菜单的组件是这样：
定位你的组件并组织你的文档样式
相关配置将会在styleguidist.config.js中进行编写。
定位组件
styleguidist使用glob pattern匹配查询你的组件，默认情况下，查询的是src/components/**/*.vue。下面这个例子，能够检测到如src/components/Button/Button.vue.
module.exports = {
components: 'src/components/**/[A-Z]*.vue'
}但不会监测同时文件夹__tests__。
注意：所有的路径都是对配置文件的相对路径。
注意：使用getComponentPathLine配置项将该变组件文档下显示的组件路径。
提示：使用ignore配置项可能排除你不想在文档中看到的文件。
加载和暴露组件
styleguidist默认情况下在你文档的示例展示中加载你的组件并暴露给全局。如果不想因此造成全局污染，可以使用locallyRegisterCompenents，这样就能保证你的组件只在该组件的ReadMe.md文件和
分组
给你的组件进行分组在文档中展示。每个分组都包含以下部分（所有的字段都是可选的）:
-
name——分组标题 -
content——包含分组概述内容Markdown文件的路径 -
components——这个和根节点下components配置项相同，可以为一个或多个glob pattern字符串，组件路径数组，或者是个返回组件路径数组或golb pattern字符串数组的函数。 -
sections——子分组的数组（支持循环嵌套） -
exampleMode——文档中代码示例的标签初始化状态，决定是否展开。 -
usageMode——文档中属性和方法的标签初始化状态，决定是否展开 -
ignore——不应包含在分组中文件路径的glob pattern的字符串或数组 -
href——一个导航路径 -
external——如果设置，连接将在新窗口打开