1.1.1 • Published 2 years ago
vuepress-apidoc v1.1.1
vuepress-apidoc 简介
一个能解析 jsdoc 注释和 vue 文件并生成 api 文档的 vuepress 插件
功能
- 根据 js、vue 文件 jsdoc 注释输出 markdown 文件；
- 展示 vue 组件，配合使用我的另一个 vuepress 插件，vuepress-plugin-vue-compdemo，识别自定义 md 容器，基本可以和 element-ui 一样的展示效果，具体参考该插件说明文档
- 可自定义分类输出侧边文档导航栏；
- 兼容 vuepress 目前所有版本 v0.x、v1.x 和 v2.x；
生成 jsdoc 注释
- 一般 vscode 有很多这类的插件：一般我是用的是 Document This
起步
# 安装
npm i -D vuepress-apidoc
# 生成api文档
vuepress-apidoc -c 配置文件路径
# 例如，自行在本地创建config文件
vuepress-apidoc -c ./config/config.js
# 或
vuepress-apidoc -c ./config/config.json命令行参数
- -c：配置文件配置文件路径（必须）
- -v：查看版本号
产物
- md 文件（一般将其输出路径dist设置到 vuepress 的 docs 目录即可）
- sidebar 的 config.js 文件
使用 sidebar 的 config.js 文件
- 一般是在 vuepress 项目的配置文件中引入
- 例如：vuepress 的 v2.x 版本的配置文件在.../docs/.vuepress/config.js 中引入
// docs/.vuepress/config.js
// 引入导出的sidebar配置config.js
const { getApiSidebarList } = require('../api/config')
let sidebarList = {
// 这里可以写你其他的侧边栏导航
// 例如
// v1.x、v0.x
// '/other/': [
// {
// title: 'other',
// collapsable: false, // 可选的, 默认值是 true,
// children: ['/other/other.md']
// }
// v2.x
// '/other/': [
// {
// text: 'other',
// children: [
// '/other/other.md'
// ]
// }
// ]
}
// 将getApiSidebarList()返回的对象，覆盖到sidebarList
sidebarList = Object.assign({}, sidebarList, getApiSidebarList())
// vuepress配置
module.exports = {
themeConfig: {
sidebar: sidebarList
}
}config 配置文件
接受两种文件格式：.js 或者.json
src（array）：js 文件目录或文件路径
- rotuerName（string）：输出 vuepress 导航路由名，默认：'api'
- dist（string）：markdown 文件和 sidebar 配置文件输出目录路径，默认：'../docs'
- readme（object）：rotuerName路由下的首页 README.md 文件配置，若不设置，则默认输出所有 api 的 md 文件列表并写出新的 README.md
- path（string）：输入的 README.md 文件路径，默认：空
- outputName（string）：输出名称，默认：README.md
- isOutputApiList（boolean）：是否在 README.md 最后追加所有 api 的 md 文件列表数据，默认：true
- sidebarTree（array）：自定义 vuepress 的 sidebar 分类，默认：归类到 API 栏下
- title（string）: 分类名称
- include（array）: 该分类包含的源文件匹配，多个规则只要符合一个规则就会添加
- exclude（array）: 该分类忽略的源文件匹配，多个规则只要符合一个规则就会忽略
- info（boolean）：是否输出详情日志，默认：true
- include（array）：包含的源文件匹配，多个规则只要符合一个规则就会添加
- exclude（array）：忽略的源文件匹配，多个规则只要符合一个规则就会忽略
- vuepressVersion（number）：vuepress 的版本，例如 v1.x，则vuepressVersion:1，默认：2
- defaultSiebarName：默认的侧边栏分类名称，默认：'API'
- jsdoc（object）：jsdoc 的配置
- configure（string）： getJsdocData 的 configure 配置项，既是 jsdoc 的配置文件路径
vueDoc（object）：vue 文件文档配置
- autoOutput（object）：vue 文件输出的 md 文档配置，默认都为 true，如果不需要则设置对应的为 false 即可
- title（boolean）: 默认：true，是否输出顶部的 title
- props（boolean）: 默认：true，是否输出 props
- slot（boolean）: 默认：true，是否输出 slot
- method（boolean）: 默认：true，是否输出 method
- event（boolean）: 默认：true，是否输出 event
注意
- 该插件是根据配置文件所在目录作为源的根目录
- 例如配置文件路径在：E:\code\vuepress-apidoc\config\config.js
- 那么相对路径就是根据 E:\code\vuepress-apidoc\config，作相对的
- 在 config.js 配置项中写，"../src"，那么他的路径就是，E:\code\vuepress-apidoc\src
- 也可以在 config.js 配置 info 属性为 true，查看路径是否正确
文件匹配写法
config.js
const config = {
src: ['../src'],
rotuerName: 'api',
dist: '../docs',
defaultSiebarName: 'API',
readme: {
path: '../README.md',
outputName: 'README.md',
isOutputApiList: false
},
sidebarTree: [
{
title: '工具类',
include: ['utils/**'],
exclude: []
}
],
info: false,
include: ['*.js'],
exclude: ['node_modules'],
vuepressVersion: 2,
// jsdoc: {
// configure: ''
// },
// vue doc文档配置
vueDoc: {
// 输出配置，是否需要自动检测文件输出对应的 event、props、slot、method，默认都为true，如果不需要则设置对应的为false即可
autoOutput: {
title: true,
// 是否输出props
props: true,
slot: true,
method: true,
event: true
}
}
}
module.exports = configjs 文件的 jsdoc
- 写法可以参考jsdoc
/**
* 订阅事件
* @param {*} type 事件名
* @param {*} scope 作用域
* @param {*} callback 回调
* @param {*} [params=[]] 回调参数
* @memberof EventManager
*/
on(type, scope, callback, params = []) {
// 订阅的放到数组记录
const listenerParams = { callback: callback, scope: scope, params: params, isOnce: false }
this.addListener(type, listenerParams)
}vue 文件的 jsdoc
- 写法可以参考 vue-docgen-api、jsdoc
<template>
<div class="Button">
<button class="button" @click.prevent="onClick" :style="{ color: color, fontSize: fontSize }">
<!-- @slot 这里是slot的jsdoc
@binding {object} text text of the menu item
-->
<slot name="test" :text="fontSize"> </slot>
<button @click="click">点击</button>
</button>
</div>
</template>
<script>
/**
* 这里是组件的描述
*/
export default {
name: 'Button',
props: {
/**
* The color for the button.
*/
color: {
type: String,
default: '#333'
},
/**
* The size of the button 其他的东西ddd
* @values small, normal, large,ls
*
*/
size: {
type: String,
default: 'normal'
},
/**
* Gets called when the user clicks on the button
* @ignore
*/
onClick: {
type: Function,
default: (event) => {
console.log('You have clicked me!', event.target)
}
}
},
computed: {
fontSize() {
let size
switch (this.size) {
case 'small':
size = '10px'
break
case 'normal':
size = '14px'
break
case 'large':
size = '18px'
break
}
return size
}
},
methods: {
/**
* Sets the order2222
* @public
* @version 1.0.5
* @since Version 1.0.1
*/
click() {
/**
* 这里是events的jsdoc
* @event click
* @property {number} newVal new value set
* @property {number} oldVal new value set
* @params {number} newVal
*/
this.$emit('click', newVal, oldVal)
}
}
}
</script>
<style scope>
.checks {
background-image: linear-gradient(45deg, #f5f5f5 25%, transparent 25%), linear-gradient(-45deg, #f5f5f5 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f5f5f5 75%), linear-gradient(-45deg, transparent 75%, #f5f5f5 75%);
background-size: 16px 16px;
background-position: 0 0, 0 8px, 8px -8px, -8px 0px;
}
</style>
<!-- 直接引入md文件 -->
<docs>
<demo>./Button.md</demo>
</docs>如何在 vue 文件中直接引入 markdown 文件
- 插件会直接读取\...\ 中间的路径文件内容，并输出到最后的 md 文件中
- 如果有需要可以输入多个 demo，但是一般一个就够了
- md 文件中，可以是任何 md 内容或是组件的演示文档vuepress-plugin-vue-compdemo
<!-- 像这样就可以了-->
<docs>
<demo> 文件路径1 </demo>
<demo> 文件路径2 </demo>
</docs>