127.使用vuepress生成项目组件库文档

使用vuepress生成项目组件库文档.jpeg

最近在看杨村长得vue-devui搭建开源系列的视频，学到一招怎么搭建开源组件库文档，由于他们的项目vite项目，所以他们引用的是vitepress，而我用的vuepress适合使用webpack构建的项目，话不多说，我们来看看怎么搭建的。

1、首先，安装vuepress

npm install vuepress -D

2、然后，在scripts中编写启动命令

    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",

然后执行npm run docs:dev发现报错问题，发现我们的vue版本之前是2.6.10，提示我们需要安装vue2.7.14版本，所以接下来升级vue版本，升级vue版本同时vue-template-compiler和vue版本要保持一致
3、升级完后，再次启动，右侧会出现一个搜索框，说明启动成功了，接下来可以进行一些其他配置。

4、配置vuepress，在根目录新建docs目录，新建.vuepress目录，新建config.js文件
目录结构如下：

image.png

简单对文档库名字进行配置，左侧菜单栏通过sidebar进行配置。

const sidebarConfig = require('./sidebarConfig')
module.exports = {
  title: 'XX组件库',
  description: 'Just playing around',
  themeConfig: {
    sidebar: sidebarConfig
  }
}

考虑到第一次没有这些文档，需要我们手动进行创建，因此，我写了一个简单的脚本，对组件库下所有的组件进行遍历并且根据遍历到的组件名生成对应的.md文件。
5、在package.json中添加脚本"create:docs": "node command/createDocs.js"用来自动生成文档
最终生成的内容就是以组件名生成一个相同名字的组件库文档，为了生成配置文件方便，我把配置项单独抽取出来，做成了一个sidebarConfig.js配置文件，在config.js中进行引入。

自动生成文档代码

// 读取组件，在docs目录生成对应的md文件
const fs = require('fs')
const path = require('path')

const basePath = path.resolve('./src/modules/base')
const docsPath = path.resolve('./docs')

const sidebarConfigs = []
fs.readdir(basePath, (error, files) => {
  if (error) {
    throw Error('error')
  } else {
    files.forEach((filename) => {
      const fileDir = path.join(basePath, filename)

      fs.stat(fileDir, (err, starts) => {
        if (err) {
          throw Error('获取文件stats失败')
        } else {
          const isFile = starts.isFile()

          //   const isDir = starts.isDirectory() // 是文件夹

          if (isFile) {
            const extname = path.extname(fileDir)
            let fileName = path.basename(fileDir)

            if (extname.includes('.vue')) {
              fileName = fileName.split('.vue')[0]

              const docsComponentPath = path.join(docsPath, fileName)
              // 判断文件是否存在，不存在再创建
              fs.stat(docsComponentPath, (err, stats) => {
                if (err) {
                  //   if (err.code === 'ENOENT') {
                  // 在指定目录下生成md文档
                  createFile(path, fileName)

                  sidebarConfigs.push([`/${fileName}`, fileName])
                  createConfig()
                  //   }
                }
              })
            }
          }
        }
      })
    })
  }
})

// 根据指定路径创建md文件
function createFile(path, fileName) {
  return new Promise((resolve, reject) => {
    fs.writeFile(path.join(docsPath, `${fileName}.md`), fileName, () => {
      resolve('文件新增成功')
    })
  })
}

// 在vuepress  config中替换原有配置内容，生成一个文件替换掉原来的
function createConfig() {
  // 收集sitebar
  return new Promise((resolve, reject) => {
    const content = `module.exports = ${JSON.stringify(sidebarConfigs)}`
    fs.writeFile(path.join(docsPath, '/.vuepress/sidebarConfig.js'), content, () => {})
  })
}

执行npm run create:docs，在本地的docs目录下会生成很多以组件名命名的md文件

重新启动npm run docs:dev

image.png

这样就算成功了，当然文档里面的内容还是需要我们手动维护的，但是每次我们只需要维护没有创建过的文档即可。

最后编辑于：2022.12.28 14:06:33