vue中如何生成組件的文檔說明

針對vue組件，編寫對應的組件文檔

• 使用vuepress直接通過markdown文件去動態生成對應的組件演示和代碼預覽以及說明。

准備工作

• 先安裝vuepress，npm i vuepress -D。
• 接着安裝vuepress-plugin-demo-container，npm i vuepress-plugin-demo-container -D。
• 整理項目目錄:

  root

  docs

  .vuepress

  config.js

  enhanceApp.js

  ui

  test.md

  bussiness

  test.md

  src
  ...

• package.json中新增命令。

  "scripts": {
      "docs:dev": "vuepress dev docs",
      "docs:build": "vuepress build docs"
  }
  

主要配置

1. config.js。

   module.exports = {
       title: 'Test Component', // 左上角的標題
       description: 'Just a test demo.', // meta內容
       plugins: ['demo-container'], // 引用的`vuepress-plugin-demo-container`插件
       themeConfig: { // 主題配置，可以直接看文檔
           sidebar: [ // 側邊欄配置
               {
                   title: 'UI組件',
                   path: '/UI/',
                   collapsable: true,
                   children: [
                       '/UI/test'
                   ]
               },
               {
                   title: '業務組件',
                   path: '/Function/',
                   collapsable: true,
                   children: [
                       '/Function/test'
                   ]
               }
           ]
       }
   }
   

2. enhanceApp.js。

   // 通過該文件，把需要用的組件進行全局的注冊，因為在markdown中的文件不能使用import引入組件，必須要提前注冊好全局的組件
   import HelloWorld from '../../src/components/HelloWorld.vue';
   
   export default ({ 
       Vue
   }) => {
       Vue.component('HelloWorld', HelloWorld);
   }
   // 昨天發現同時注冊多個組件的時候好像有問題，只好換一種方式來實現，將組件通過一個文件拋出，然后使用Vue.use去完成組件的注冊
   import components from '../../src/components/index.js';
   const customPlugin = {};
   customPlugin.install = function(Vue, options = {}) {
       const { components } = options;
       for(let key in components) {
           if(Object.prototype.hasOwnProperty.call(components, key)) {
               Vue.component(key, components[key]);
           }
       }
   }
   
   export default ({ 
       Vue
   }) => {
       Vue.use(customPlugin { components })
   }    
   

3. test.md。::: demo [some comments]開始標志，可以在demo后面加一些注釋，:::結尾標志，用了這個開始結尾標志的就會自動去渲染它的示例以及代碼塊，script標簽中一定要有export default {}，不然不會展示它的示例效果。為了展示這塊代碼，所以把三個`號分開了，實際寫的時候是要挨在一起的。

   ### Test2
   
   ::: demo
   ` ` `vue
   <template>
       <HelloWorld msg="Nice to meet you, Jane!" />
   </template>
   <script>
   export default {}
   </script>
   ` ` `
   :::
   

查看效果

• npm run docs:dev，直接查看你的組件文檔，至此，簡單的組件預覽文檔已經可以基本使用了，其它需要的功能可以自己對着官網的api去配置。