docs: generate sidebar from plugin, push API headings to search

2026-05-29 05:14:04 +03:00 · 2019-11-20 15:55:59 -08:00
parent 7c6addf308
commit 17d360cbaf
10 changed files with 137 additions and 83 deletions
@@ -130,6 +130,16 @@ module.exports = {
            ['guide/keydown', 'Keydown Events'],
          ],
        },
+        {
+          title: 'API',
+          collapsable: false,
+          children: [
+            ['api/props', 'Props'],
+            ['api/events', 'Events'],
+            ['api/slots', 'Slots'],
+            ['api/methods', 'Methods'],
+          ],
+        },
      ],
    },
  },
@@ -0,0 +1,24 @@
+import docs from '@dynamic/api.js';
+
+export default ({Vue, options, router, siteData}) => {
+
+  ['props', 'events', 'slots', 'methods'].map(section => {
+    const page = siteData.pages.find(({path}) => path.includes(section));
+
+    if( ! page.hasOwnProperty('title') ) {
+      page.title = section.charAt(0).toUpperCase() + section.slice(1)
+    }
+
+    if (page && docs[section]) {
+      if( ! page.hasOwnProperty('headers') ) {
+        page.headers = [];
+      }
+
+      docs[section].forEach(({name}) => page.headers.push({
+        level: 2,
+        slug: name,
+        title: name,
+      }));
+    }
+  });
+}
@@ -1,5 +1,10 @@
 const docs = require('vue-docgen-api');
 const path = require('path');
+// const getMemberFilter = require('vue-docgen-api/dist/utils/getMemberFilter.js');
+const getMemberFilter = require('vue-docgen-api/dist/utils/getPropsFilter');
+const bt = require('@babel/types');
+const {NodePath} = require('ast-types');
+const {Documentation, ParseOptions, ComponentDoc} = require('vue-docgen-api');

 /**
 * Generate an object of API documentation.
@@ -7,6 +12,28 @@ const path = require('path');
 * @return {Promise<ComponentDoc>}
 */
 module.exports = async (documentationRootDir) => {
-  const file = path.resolve(documentationRootDir, '../src/components/Select.vue');
-  return await docs.parse(file);
+  const file = path.resolve(documentationRootDir,
+    '../src/components/Select.vue');
+  return await docs.parse(file, {
+    jsx: false,
+    // addScriptHandlers: [
+    //   /**
+    //    * @param {Documentation} docs
+    //    * @param {NodePath} path
+    //    * @param {bt.File} astPath
+    //    * @param {ParseOptions} options
+    //    * @return {Promise<void>}
+    //    */
+    //   function (docs, path, astPath, options) {
+    //     if (bt.isObjectExpression(path.node)) {
+    //       const propsPath = path
+    //         .get('properties')
+    //         .filter(nodePath => bt.isObjectProperty(nodePath.node) &&
+    //           getMemberFilter('props')(nodePath));
+    //
+    //
+    //     }
+    //   },
+    // ],
+  });
 };
@@ -1,5 +1,6 @@
 const path = require('path');
 const fs = require('fs');
+const chalk = require('chalk');
 const generator = require('./generator');

 /**
@@ -14,28 +15,32 @@ function getMixins (directory) {
 }

 /**
- * Dynamically generates all API documentation with vue-docgen-api.
- * Resulting object can be imported and used client-side:
- *
- * import documentation from '@dynamic/api'
- *
- * @see https://vuepress.vuejs.org/plugin/option-api.html#clientdynamicmodules
 * @param options
 * @param sourceDir
 * @return {{clientDynamicModules(): Promise<{name: string, content: string}>}}
 */
 module.exports = (options, {sourceDir}) => ({
+
  /**
-   * Generate documentation for Select.vue
+   * Dynamically generates all API documentation with vue-docgen-api.
+   * Resulting object can be imported and used client-side via:
+   * import documentation from '@dynamic/api'
+   *
+   * @see https://vuepress.vuejs.org/plugin/option-api.html#clientdynamicmodules
   * @return {Promise<{name: string, content: string}>}
   */
  async clientDynamicModules () {
    const docs = await generator(sourceDir);
-    console.log('Generated API documentation for Select.vue');
-
+    console.log(chalk.green('✅ Generated API documentation for Select.vue'));
    return {
      name: 'api.js',
      content: `export default ${JSON.stringify(docs)}`,
    };
  },
+
+  /**
+   * @see https://vuepress.vuejs.org/plugin/option-api.html#enhanceappfiles
+   */
+  enhanceAppFiles: path.resolve(__dirname, 'enhanceApp.js'),
+
 });
@@ -1,67 +0,0 @@
-<template>
-  <ul>
-    <li>
-      <section class="sidebar-group depth-0">
-        <p class="sidebar-heading open"><span>API</span></p>
-        <ul class="sidebar-links sidebar-group-items">
-          <li v-for="section in docs">
-            <router-link
-              :to="section.url"
-              :class="linkClass(section.url)"
-            >
-              {{ section.title }}
-            </router-link>
-
-            <ul v-if="section.active" class="sidebar-sub-headers">
-              <li v-for="link in section.links" :key="link" class="sidebar-sub-header">
-                <router-link
-                  :to="`${section.url}#${link}`"
-                  :class="linkClass(`${section.url}#${link}`)"
-                >
-                  {{ link }}
-                </router-link>
-              </li>
-            </ul>
-          </li>
-        </ul>
-      </section>
-    </li>
-  </ul>
-</template>
-
-<script>
-import { isActive } from '@vuepress/theme-default/util'
-import documentation from '@dynamic/api'
-
-export default {
-  name: "SideBarApi",
-  methods: {
-    isActive,
-    linkClass (path) {
-      return {
-        'active': isActive(this.$route, path),
-        'sidebar-link': true
-      }
-    },
-  },
-  computed: {
-    docs () {
-      return ['Props', 'Events', 'Slots'].map(section => {
-        const lowercase = section.toLowerCase();
-        return {
-          title: section,
-          url: `/api/${lowercase}.html`,
-          links: documentation[lowercase].map(({name}) => name).sort(),
-          active: this.isActive(this.$route, `/api/${lowercase}.html`),
-        };
-      });
-    }
-  }
-}
-</script>
-
-<style scoped>
-  ul {
-    padding-bottom: 1rem;
-  }
-</style>
@@ -1,20 +1,17 @@
 <template>
  <ParentLayout>
    <CodeFund slot="sidebar-top" />
-    <SideBarApi slot="sidebar-bottom" />
  </ParentLayout>
 </template>

 <script>
 import ParentLayout from '@parent-theme/layouts/Layout.vue'
 import CodeFund from '../components/CodeFund.vue'
-import SideBarApi from '../components/SideBarApi.vue'

 export default {
  components: {
    ParentLayout,
    CodeFund,
-    SideBarApi
  }
 }
 </script>
@@ -5,15 +5,19 @@
  "scripts": {
    "serve": "vuepress dev",
    "build": "vuepress build",
-    "build:preview": "cross-env DEPLOY_PREVIEW=true vuepress build"
+    "build:preview": "cross-env DEPLOY_PREVIEW=true vuepress build",
+    "debug": "node --inspect-brk ./node_modules/.bin/vuepress dev"
  },
  "devDependencies": {
+    "@babel/types": "^7.7.2",
    "@vuepress/plugin-active-header-links": "^1.0.0-alpha.47",
    "@vuepress/plugin-google-analytics": "^1.0.0-alpha.47",
    "@vuepress/plugin-nprogress": "^1.0.0-alpha.47",
    "@vuepress/plugin-pwa": "^1.0.0-alpha.47",
    "@vuepress/plugin-register-components": "^1.0.0-alpha.47",
    "@vuepress/plugin-search": "^1.0.0-alpha.47",
+    "ast-types": "^0.13.2",
+    "chalk": "^3.0.0",
    "cross-env": "^5.2.0",
    "fuse.js": "^3.4.4",
    "gh-pages": "^0.11.0",
@@ -675,6 +675,15 @@
    lodash "^4.17.13"
    to-fast-properties "^2.0.0"

+"@babel/types@^7.7.2":
+  version "7.7.2"
+  resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.7.2.tgz#550b82e5571dcd174af576e23f0adba7ffc683f7"
+  integrity sha512-YTf6PXoh3+eZgRCBzzP25Bugd2ngmpQVrk7kXX0i5N9BO7TFBtIgZYs7WtxtOGs8e6A4ZI7ECkbBCEHeXocvOA==
+  dependencies:
+    esutils "^2.0.2"
+    lodash "^4.17.13"
+    to-fast-properties "^2.0.0"
+
 "@hapi/address@2.x.x":
  version "2.1.0"
  resolved "https://registry.yarnpkg.com/@hapi/address/-/address-2.1.0.tgz#d86223d40c73942cc6151838d9f264997e6673f9"
@@ -732,6 +741,11 @@
  dependencies:
    "@types/babel-types" "*"

+"@types/color-name@^1.1.1":
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/@types/color-name/-/color-name-1.1.1.tgz#1c1261bbeaa10a8055bbc5d8ab84b7b2afc846a0"
+  integrity sha512-rr+OQyAjxze7GgWrSaJwydHStIhHq2lvY3BOC2Mj7KnzI7XK0Uw1TOOdI9lDoajEbSWLiYgoo4f1R51erQfhPQ==
+
 "@types/events@*":
  version "3.0.0"
  resolved "https://registry.yarnpkg.com/@types/events/-/events-3.0.0.tgz#2862f3f58a9a7f7c3e78d79f130dd4d71c25c2a7"
@@ -1299,6 +1313,14 @@ ansi-styles@^3.2.0, ansi-styles@^3.2.1:
  dependencies:
    color-convert "^1.9.0"

+ansi-styles@^4.1.0:
+  version "4.2.0"
+  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.2.0.tgz#5681f0dcf7ae5880a7841d8831c4724ed9cc0172"
+  integrity sha512-7kFQgnEaMdRtwf6uSfUnVr9gSGC7faurn+J/Mv90/W+iTtN0405/nLdopfMWwchyxhbGYl6TC4Sccn9TUkGAgg==
+  dependencies:
+    "@types/color-name" "^1.1.1"
+    color-convert "^2.0.1"
+
 anymatch@^2.0.0:
  version "2.0.0"
  resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-2.0.0.tgz#bcb24b4f37934d9aa7ac17b4adaf89e7c76ef2eb"
@@ -1423,6 +1445,11 @@ ast-types@0.12.4, ast-types@^0.12.2:
  resolved "https://registry.yarnpkg.com/ast-types/-/ast-types-0.12.4.tgz#71ce6383800f24efc9a1a3308f3a6e420a0974d1"
  integrity sha512-ky/YVYCbtVAS8TdMIaTiPFHwEpRB5z1hctepJplTr3UW5q8TDrpIMCILyk8pmLxGtn2KCtC/lSn7zOsaI7nzDw==

+ast-types@^0.13.2:
+  version "0.13.2"
+  resolved "https://registry.yarnpkg.com/ast-types/-/ast-types-0.13.2.tgz#df39b677a911a83f3a049644fb74fdded23cea48"
+  integrity sha512-uWMHxJxtfj/1oZClOxDEV1sQ1HCDkA4MG8Gr69KKeBjEVH0R84WlejZ0y2DcwyBlpAEMltmVYkVgqfLFb2oyiA==
+
 async-each@^1.0.1:
  version "1.0.3"
  resolved "https://registry.yarnpkg.com/async-each/-/async-each-1.0.3.tgz#b727dbf87d7651602f06f4d4ac387f47d91b0cbf"
@@ -1976,6 +2003,14 @@ chalk@^2.0.0, chalk@^2.3.2, chalk@^2.4.1, chalk@^2.4.2:
    escape-string-regexp "^1.0.5"
    supports-color "^5.3.0"

+chalk@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-3.0.0.tgz#3f73c2bf526591f574cc492c51e2456349f844e4"
+  integrity sha512-4D3B6Wf41KOYRFdszmDqMCGq5VV/uMAB273JILmO+3jAlh8X4qDtdtgCR3fxtbLEMzSx22QdhnDcJvu2u1fVwg==
+  dependencies:
+    ansi-styles "^4.1.0"
+    supports-color "^7.1.0"
+
 character-parser@^2.1.1:
  version "2.2.0"
  resolved "https://registry.yarnpkg.com/character-parser/-/character-parser-2.2.0.tgz#c7ce28f36d4bcd9744e5ffc2c5fcde1c73261fc0"
@@ -2125,12 +2160,19 @@ color-convert@^1.9.0, color-convert@^1.9.1:
  dependencies:
    color-name "1.1.3"

+color-convert@^2.0.1:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3"
+  integrity sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==
+  dependencies:
+    color-name "~1.1.4"
+
 color-name@1.1.3:
  version "1.1.3"
  resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.3.tgz#a7d0558bd89c42f795dd42328f740831ca53bc25"
  integrity sha1-p9BVi9icQveV3UIyj3QIMcpTvCU=

-color-name@^1.0.0:
+color-name@^1.0.0, color-name@~1.1.4:
  version "1.1.4"
  resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2"
  integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==
@@ -3728,6 +3770,11 @@ has-flag@^3.0.0:
  resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-3.0.0.tgz#b5d454dc2199ae225699f3467e5a07f3b955bafd"
  integrity sha1-tdRU3CGZriJWmfNGfloH87lVuv0=

+has-flag@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
+  integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
+
 has-symbols@^1.0.0:
  version "1.0.0"
  resolved "https://registry.yarnpkg.com/has-symbols/-/has-symbols-1.0.0.tgz#ba1a8f1af2a0fc39650f5c850367704122063b44"
@@ -7515,6 +7562,13 @@ supports-color@^6.1.0:
  dependencies:
    has-flag "^3.0.0"

+supports-color@^7.1.0:
+  version "7.1.0"
+  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-7.1.0.tgz#68e32591df73e25ad1c4b49108a2ec507962bfd1"
+  integrity sha512-oRSIpR8pxT1Wr2FquTNnGet79b3BWljqOuoW/h4oBhxJ/HUbX5nX6JSruTkvXDCFMwDPvsaTTbvMLKZWSy0R5g==
+  dependencies:
+    has-flag "^4.0.0"
+
 svg-tags@^1.0.0:
  version "1.0.0"
  resolved "https://registry.yarnpkg.com/svg-tags/-/svg-tags-1.0.0.tgz#58f71cee3bd519b59d4b2a843b6c7de64ac04764"