最近在搭建 Vue3 组件库的时候，需要提供一个组件文档的自动生成能力。Vue3 的单文件组件的 props、slots、emits、methods 等信息其实已经提供了一部分文档信息（props中的 type、default 等字段），所以我的第一想法就是通过提取 AST 中的相关信息，结合注释来生成组件的文档。大概搜了一下市面上现有的工具，目前还没有发现支持 Vue3 的，只能自己来实现一个。
安装
# for local
npm i doc-vue
# for global
npm i -g doc-vue
文档写法
在代码中的 “slot”、“props”、“emits”、“methods” 定义处添加以 “@doc” 开头的注释作为 api 描述。
<template>
<div class="component-crt-crud">
<!-- @doc the custom actions buttons -->
<slot name="customAction"></slot>
<!-- @doc the modal content -->
<slot name="modal"></slot>
</div>
</template>
<script lang="ts">
import { defineComponent} from 'vue';
export default defineComponent({
props: {
// @doc name of crud
crudName: {
type: String,
default: '',
},
// @doc modal form fieds
modalFormSchema: {
type: Array as PropType<SearchSchema[]>,
default: () => [],
},
},
emits: [
// @doc download button click event
'downloadClick',
],
setup() {
return {};
},
methods: {
/**
* @doc show detal
* @param record detail data object
*/
async show(record: BaseObject) {
//...
},
// @doc fetch table data
async fetchList() {
//...
},
},
});
</script>
在命令行中使用
docvue xxx.vue xxx.json
"xxx.vue" 是你的 vue 文件路径, "xxx.json" 是 API 文档文件路径.
输出的文档格式
根据输入的文档文件的后缀名，会自动生成以下格式之一的 API 文档: "json\md\html"，默认为 "json"。 查看 demo。
# 输出一个 json 文件
docvue xxx.vue xxx.json
# 输出一个 markdown 文件
docvue xxx.vue xxx.md
# 输出一个 html 文件
docvue xxx.vue xxx.html
在 Nodejs 中使用
docvue 为一个函数，接受2个参数，第一个为源码字符串，第二个为选项对象，返回文档数据。
const docvue = require('doc-vue');
const code = `your code`;
const result = docvue(code); // by default, result is json object
const mdResult = docvue(code, {type: 'html'}); // result is markdown string
选项
type
docvue 函数的指定文档类型，输入其中之一：“json\md\html”，默认为“json”。
License
MIT
