開發(fā)中文檔是必不可少的, 但是目前前端可謂是百花齊放, 各種自定義的編譯器,后綴名, 導(dǎo)致目前還沒有一個(gè)很好用的文檔生成工具, 可以快速生成整個(gè)項(xiàng)目的文檔, 隨著項(xiàng)目越來(lái)越大, 越來(lái)越多, 對(duì)企業(yè)整體的技術(shù)管控也帶來(lái)越來(lái)越大的挑戰(zhàn), 如何知道企業(yè)內(nèi)部已經(jīng)開發(fā)了哪些組件, 哪些功能有寫好的庫(kù)可以直接調(diào)用, 這些都需要一個(gè)文檔工具來(lái)進(jìn)行歸納匯總
基于以上問題, 筆者使用node + vue3 + vite 開發(fā)了一個(gè)文檔生成器 特性如下
基于標(biāo)準(zhǔn)注釋 /* */ 只需要正常開發(fā)中寫好注釋 文檔就已經(jīng)好了
不限定語(yǔ)言 框架, 只讀取文件里的/* /標(biāo)準(zhǔn)注釋 不管是vue項(xiàng)目 react項(xiàng)目還是其他的 只要文件里能寫 / */ 這種形式的注釋
開發(fā)模式 實(shí)時(shí)獲取文檔數(shù)據(jù) 打包模式 打包數(shù)據(jù)隨意部署
自定義文件分類, 自定義文件內(nèi)變量 方法分類
顯示文件引用鏈 可以清晰看到當(dāng)前文件都引用了其他哪些文件
界面展示如下:
原理其實(shí)很簡(jiǎn)單, 就是解析 /* */形式的注釋 并根據(jù)指定的@開頭的key值 解析相關(guān)數(shù)據(jù)
目前定義的key值如下:
@doc
此段注釋是否要解析成文檔
@fileDoc
是否文件描述文檔
@type
文檔分類 文件描述注釋和文件內(nèi)的注釋根據(jù)這個(gè)字段進(jìn)行分類
@author
作者 文件作者和文件內(nèi)部方法 變量等的作者
@name
展示到頁(yè)面上的名稱
@desc
描述
@param
入?yún)?/p>
@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
}
可以看出都是標(biāo)準(zhǔn)注釋
安裝使用
項(xiàng)目已打成npm包, 可以在任意項(xiàng)目里使用, 或者全局安裝也可以
npm install @xpf0000/docs
docs // 展示此項(xiàng)目的文檔
docs src // 展示src目錄下的文檔
docs src --build outSrc // 打包src目錄下的文檔到outSrc
github: https://github.com/xpf0000/docs
