# vuepress-apidoc

**Repository Path**: DoLaMi/vuepress-apidoc

## Basic Information

- **Project Name**: vuepress-apidoc
- **Description**: 一个根据 jsdoc 注释生成 api 文档的 vuepress 插件
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-10-25
- **Last Updated**: 2023-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vuepress, vuepress-plugin, jsdoc, Markdown

## README

### vuepress-apidoc 简介

> 一个能解析 jsdoc 注释和 vue 文件并生成 api 文档的 vuepress 插件

### 功能

- 根据 js、vue 文件 <code>jsdoc</code> 注释输出 <code>markdown</code> 文件；
- 展示 vue 组件，配合使用我的另一个 vuepress 插件，<code>[vuepress-plugin-vue-compdemo](https://www.npmjs.com/package/vuepress-plugin-vue-compdemo)</code>，识别自定义 md 容器，基本可以和 element-ui 一样的展示效果，具体参考该插件说明文档
  ![效果](https://gitee.com/DoLaMi/vuepress-plugin-vue-compdemo/raw/master/plugin/md-img/comp-demo-2.jpg)
- 可自定义分类输出侧边文档导航栏；
- 兼容 vuepress 目前所有版本 <code>v0.x</code>、<code>v1.x</code> 和 <code>v2.x</code>；

![展示](https://gitee.com/DoLaMi/vuepress-apidoc/raw/master/readme-img/v2.jpg)

### 生成 jsdoc 注释

- 一般 vscode 有很多这类的插件：一般我是用的是<code> [Document This](https://marketplace.visualstudio.com/items?itemName=oouo-diogo-perdigao.docthis)</code>

### 起步

```bash
# 安装
npm i -D vuepress-apidoc

# 生成api文档
vuepress-apidoc -c 配置文件路径

# 例如，自行在本地创建config文件
vuepress-apidoc -c ./config/config.js

# 或
vuepress-apidoc -c ./config/config.json
```

### 命令行参数

- <code>-c</code>：配置文件配置文件路径（必须）
- <code>-v</code>：查看版本号

### 产物

- md 文件（一般将其输出路径<code>dist</code>设置到 vuepress 的 docs 目录即可）
- sidebar 的 <code>config.js</code> 文件

### 使用 sidebar 的 config.js 文件

- 一般是在 vuepress 项目的配置文件中引入
- 例如：vuepress 的 v2.x 版本的配置文件在.../docs/.vuepress/config.js 中引入

```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 配置文件

- 接受两种文件格式：<code>.js</code> 或者<code>.json</code>

- <code>src</code>（array）：js 文件目录或文件路径
- <code>rotuerName</code>（string）：输出 vuepress 导航路由名，默认：<code>'api'</code>
- <code>dist</code>（string）：markdown 文件和 sidebar 配置文件输出目录路径，默认：<code>'../docs'</code>
- <code>readme</code>（object）：<code>rotuerName</code>路由下的首页 README.md 文件配置，若不设置，则默认输出所有 api 的 md 文件列表并写出新的 README.md
  - <code>path</code>（string）：输入的 README.md 文件路径，默认：<code>空</code>
  - <code>outputName</code>（string）：输出名称，默认：<code>README.md</code>
  - <code>isOutputApiList</code>（boolean）：是否在 README.md 最后追加所有 api 的 md 文件列表数据，默认：<code>true</code>
- <code>sidebarTree</code>（array）：自定义 vuepress 的 sidebar 分类，默认：<code>归类到 API 栏下</code>
  - <code>title</code>（string）: 分类名称
  - <code>include</code>（array）: 该分类包含的源文件匹配，多个规则只要符合一个规则就会添加
  - <code>exclude</code>（array）: 该分类忽略的源文件匹配，多个规则只要符合一个规则就会忽略
- <code>info</code>（boolean）：是否输出详情日志，默认：<code>true</code>
- <code>include</code>（array）：包含的源文件匹配，多个规则只要符合一个规则就会添加
- <code>exclude</code>（array）：忽略的源文件匹配，多个规则只要符合一个规则就会忽略
- <code>vuepressVersion</code>（number）：vuepress 的版本，例如 v1.x，则<code>vuepressVersion</code>:<code>1</code>，默认：<code>2</code>
- <code>defaultSiebarName</code>：默认的侧边栏分类名称，默认：<code>'API'</code>
- <code>jsdoc</code>（object）：jsdoc 的配置
  - <code>configure</code>（string）： getJsdocData 的 configure 配置项，既是 jsdoc 的配置文件路径
- <code>vueDoc</code>（object）：vue 文件文档配置

  - <code>autoOutput</code>（object）：vue 文件输出的 md 文档配置，默认都为 true，如果不需要则设置对应的为 false 即可
  - <code>title</code>（boolean）: <code>默认：true</code>，是否输出顶部的 title
  - <code>props</code>（boolean）: <code>默认：true</code>，是否输出 props
  - <code>slot</code>（boolean）: <code>默认：true</code>，是否输出 slot
  - <code>method</code>（boolean）: <code>默认：true</code>，是否输出 method
  - <code>event</code>（boolean）: <code>默认：true</code>，是否输出 event

### 注意

- 该插件是根据配置文件所在目录作为源的根目录
- 例如配置文件路径在：E:\code\vuepress-apidoc\config\config.js
- 那么相对路径就是根据 E:\code\vuepress-apidoc\config，作相对的
- 在 <code>config.js</code> 配置项中写，<code>"../src"</code>，那么他的路径就是，E:\code\vuepress-apidoc\src
- 也可以在 <code>config.js</code> 配置 <code>info</code> 属性为 <code>true</code>，查看路径是否正确

### 文件匹配写法

- 参考：[micromatch 的 contains 方法](https://www.npmjs.com/package/micromatch#contains)

### config.js

```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 = config
```

### js 文件的 jsdoc

- 写法可以参考[jsdoc](https://jsdoc.zcopy.site/)

```js
  /**
   * 订阅事件
   * @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](https://www.npmjs.com/package/vue-docgen-api)、[jsdoc](https://jsdoc.zcopy.site/)

```html
<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 文件

- 插件会直接读取\<demo>...\</demo> 中间的路径文件内容，并输出到最后的 md 文件中
- 如果有需要可以输入多个 demo，但是一般一个就够了
- md 文件中，可以是任何 md 内容或是组件的演示文档[vuepress-plugin-vue-compdemo](https://www.npmjs.com/package/vuepress-plugin-vue-compdemo)

```html
<!-- 像这样就可以了-->
<docs>
  <demo> 文件路径1 </demo>
  <demo> 文件路径2 </demo>
</docs>
```

### 参考

- [micromatch](https://www.npmjs.com/package/micromatch#contains)
- [vuepress](https://vuepress.vuejs.org/zh)
- [commander](https://github.com/tj/commander.js/blob/HEAD/Readme_zh-CN.md)
- [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown)
- [vue-docgen-api](https://www.npmjs.com/package/vue-docgen-api)
- [vuepress-jsdoc](https://github.com/ph1p/vuepress-jsdoc)
- [vuepress-plugin-vue-compdemo](https://www.npmjs.com/package/vuepress-plugin-vue-compdemo)