开发中文档是必不可少的, 但是目前前端可谓是百花齐放, 各种自定义的编译器,后缀名, 导致目前还没有一个很好用的文档生成工具, 可以快速生成整个项目的文档, 随着项目越来越大, 越来越多, 对企业整体的技术管控也带来越来越大的挑战, 如何知道企业内部已经开发了哪些组件, 哪些功能有写好的库可以直接调用, 这些都需要一个文档工具来进行归纳汇总
基于以上问题, 笔者使用node + vue3 + vite 开发了一个文档生成器 特性如下
基于标准注释 /* */ 只需要正常开发中写好注释 文档就已经好了
不限定语言 框架, 只读取文件里的/* /标准注释 不管是vue项目 react项目还是其他的 只要文件里能写 / */ 这种形式的注释
开发模式 实时获取文档数据 打包模式 打包数据随意部署
自定义文件分类, 自定义文件内变量 方法分类
显示文件引用链 可以清晰看到当前文件都引用了其他哪些文件
界面展示如下:
企业微信截图_c004dcf6-819f-495f-9dde-58767ca4e368.png
原理其实很简单, 就是解析 /* */形式的注释 并根据指定的@开头的key值 解析相关数据
目前定义的key值如下:
@doc
此段注释是否要解析成文档
@fileDoc
是否文件描述文档
@type
文档分类 文件描述注释和文件内的注释根据这个字段进行分类
@author
作者 文件作者和文件内部方法 变量等的作者
@name
展示到页面上的名称
@desc
描述
@param
入参
@returns
返回
文件注释如下
/**
* @doc true
* @fileDoc true
* @author xupengfei
* @name Utils.js
* @type core
* @desc global method extend
*/
const fs = require('fs')
const path = require('path')
/**
* @doc true
* @name findFile
* @desc find all file by location dir path
* @param base location dir path
* @returns [] all file in location dir path
*/
const findFile = (base) => {
const files = []
fs.readdirSync(base).forEach((file) => {
const curPath = path.join(base, file)
if (fs.existsSync(curPath)) {
const stat = fs.lstatSync(curPath)
if (!stat.isSymbolicLink()) {
if (stat.isFile()) {
files.push(curPath)
} else if (stat.isDirectory()) {
const sub = findFile(curPath)
files.push(...sub)
}
}
}
})
return files
}
/**
* @doc true
* @name uuid
* @desc make uuid string
* @param length uuid string length
* @returns string uuid string
*/
const uuid = (length = 32) => {
const num = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'
let str = ''
for (let i = 0; i < length; i++) {
str += num.charAt(Math.floor(Math.random() * num.length))
}
return str
}
module.exports = {
findFile,
uuid
}
可以看出都是标准注释
安装使用
项目已打成npm包, 可以在任意项目里使用, 或者全局安装也可以
npm install @xpf0000/docs
docs // 展示此项目的文档
docs src // 展示src目录下的文档
docs src --build outSrc // 打包src目录下的文档到outSrc
github: https://github.com/xpf0000/docs
