docs: update API page structure (vuetifyjs#14069)

strstr1 · Aug 26, 2021 · ae8aa75 · ae8aa75
1 parent 32dcb06
commit ae8aa75
Show file tree

Hide file tree

Showing 95 changed files with 287 additions and 211 deletions.
diff --git a/packages/api-generator/src/index.js b/packages/api-generator/src/index.js
@@ -204,15 +204,9 @@ const getCompleteApi = locales => {
   ].sort((a, b) => a.name.localeCompare(b.name))
 }
 
-const getHeaderLocale = locale => {
-  const { headers } = loadLocale('generic', locale)
-  return headers || {}
-}
-
 module.exports = {
   getApi,
   getCompleteApi,
   getComponentsApi,
   getDirectivesApi,
-  getHeaderLocale,
 }
diff --git a/packages/api-generator/src/locale/en/generic.json b/packages/api-generator/src/locale/en/generic.json
@@ -24,8 +24,5 @@
   "events": {
     "click": "Event that is emitted when the component is clicked",
     "input": "The updated bound model"
-  },
-  "headers": {
-    "links": "Component Pages"
   }
 }
diff --git a/packages/docs/.markdownlintrc b/packages/docs/.markdownlintrc
@@ -29,6 +29,7 @@
       "home-vuetify-logo",
       "icon-list",
       "inline-ad",
+      "inline-api",
       "kbd",
       "premium-themes",
       "promoted-ad",

diff --git a/packages/docs/build/api-plugin.js b/packages/docs/build/api-plugin.js
@@ -1,8 +1,9 @@
 // Imports
 const fs = require('fs')
+const path = require('path')
 const { resolve } = require('path')
 const { startCase } = require('lodash')
-const { getApi, getCompleteApi, getHeaderLocale } = require('@vuetify/api-generator')
+const { getApi, getCompleteApi } = require('@vuetify/api-generator')
 const rimraf = require('rimraf')
 
 const localeList = require('../src/i18n/locales').map(item => item.alternate || item.locale)
@@ -20,7 +21,7 @@ function genApiLinks (component, header) {
   if (!links.length || !header) return ''
 
   const section = [
-    `## ${header}`,
+    `## ${header} {#links}`,
     links.join('\n'),
   ]
 
@@ -57,14 +58,35 @@ function genFooter () {
 
 const sanitize = str => str.replace(/\$/g, '')
 
+function loadMessages (locale) {
+  const prefix = path.resolve('./src/i18n/messages/')
+  const fallback = require(path.join(prefix, 'en.json'))
+
+  try {
+    const messages = require(path.join(prefix, `${locale}.json`))
+
+    return {
+      ...fallback['api-headers'],
+      ...(messages['api-headers'] || {}),
+    }
+  } catch (err) {
+    return fallback['api-headers']
+  }
+}
+
 function createMdFile (component, data, locale) {
-  const headerLocale = getHeaderLocale(locale)
+  const messages = loadMessages(locale)
   let str = ''
 
   str += genHeader(component)
-  str += genApiLinks(component, headerLocale.links)
+  str += genApiLinks(component, messages.links)
 
-  str += `<api-section name="${component}" />\n\n`
+  for (const section of ['props', 'functions', 'events', 'slots', 'sass', 'options', 'argument', 'modifiers']) {
+    if (Array.isArray(data[section]) && data[section].length) {
+      str += `## ${messages[section]} {#${section}}\n\n`
+      str += `<api-section name="${component}" section="${section}" />\n\n`
+    }
+  }
 
   str += genFooter()
 

diff --git a/packages/docs/build/toc-loader.js b/packages/docs/build/toc-loader.js
@@ -17,12 +17,12 @@ function getPageHeadings (page) {
 
     const next = tokens[i + 1]
     const link = next.children.find(child => child.type === 'link_open')
-    const text = next.content
+    const text = next.children.find(child => child.type === 'text' && child.content.trim())
     const anchor = !link || link.attrs.find(([attr]) => attr === 'href')
     const [, to] = anchor
 
     headings.push({
-      text,
+      text: text.content,
       to,
       level,
     })

diff --git a/packages/docs/src/components/api/ApiSection.vue b/packages/docs/src/components/api/ApiSection.vue
@@ -1,69 +1,23 @@
 <template>
-  <div v-if="inlineApi || name">
-    <v-row
-      class="mb-2"
-      justify="space-between"
-      no-gutters
-    >
-      <v-col
-        class="mt-2"
-        cols="12"
-        sm="5"
-        md="4"
-      >
-        <app-select
-          v-if="apiComponents.length > 1"
-          :value="selectedComponent"
-          icon="$mdiViewDashboardOutline"
-          :items="apiComponents"
-          @input="selectedComponent = $event"
-        />
-      </v-col>
-      <v-col
-        class="mt-2"
-        cols="12"
-        sm="5"
-        md="4"
-      >
-        <app-text-field
-          clearable
-          icon="$mdiMagnify"
-          label="Filter"
-          @input="filter = $event"
-        />
-      </v-col>
-    </v-row>
-    <v-row
-      v-for="(apiData, field) in apiComponent"
-      :key="field"
-      cols="12"
-      no-gutters
-    >
-      <v-col>
-        <app-heading
-          v-if="!hideHeader"
-          :id="`api-${field}`"
-          class="text-capitalize"
-          :content="$t(`api-headers.${field}`)"
-          :href="`#api-${field}`"
-          :level="name ? '2' : '3'"
-        />
-        <api-table
-          :api-data="apiData"
-          class="mb-4"
-          :field="field"
-          :filter="filter"
-          :page="name"
-        />
-      </v-col>
-    </v-row>
+  <div>
+    <div class="d-flex mb-2">
+      <app-text-field
+        clearable
+        icon="$mdiMagnify"
+        label="Filter"
+        @input="filter = $event"
+      />
+    </div>
+    <api-table
+      :api-data="apiData"
+      class="mb-4"
+      :field="section"
+      :filter="filter"
+    />
   </div>
 </template>
 
 <script>
-  import { get, sync } from 'vuex-pathify'
-  import pageToApi from '@/data/page-to-api'
-
   const getApi = name => {
     return import(
       /* webpackChunkName: "api-data" */
@@ -76,65 +30,27 @@
     name: 'ApiSection',
 
     props: {
-      hideHeader: Boolean,
       name: String,
-      page: String,
       section: String,
     },
 
     data: () => ({
-      apiComponents: [],
-      selectedComponent: {},
       filter: null,
+      apiData: [],
     }),
 
-    computed: {
-      inlineApi: get('user/api'),
-      toc: sync('pages/toc'),
-      apiComponent () {
-        return Object.keys(this.selectedComponent)
-          .filter(key => this.section ? this.section === key : !['component', 'mixins', 'name'].includes(key))
-          .reduce((obj, key) => {
-            if (this.selectedComponent[key].length) {
-              obj[key] = this.selectedComponent[key]
-            }
-            return obj
-          }, {})
-      },
-    },
-
     async created () {
-      const components = this.name ? [this.name] : pageToApi[this.page] || []
+      try {
+        const api = (await getApi(this.name)).default
 
-      if (!components.length) {
-        throw new Error(`API for ${this.name || this.page} does not exist`)
-      }
+        if (!api[this.section]) {
+          throw new Error(`API section "${this.section}" for "${this.name}" does not exist`)
+        }
 
-      for (const component of components) {
-        this.apiComponents.push({
-          text: component,
-          value: (await getApi(component)).default,
-        })
+        this.apiData = api[this.section] || []
+      } catch (err) {
+        console.error(err)
       }
-      this.selectedComponent = this.apiComponents[0].value
-      if (this.name && !this.section) {
-        this.updateToc()
-      }
-    },
-
-    methods: {
-      updateToc () {
-        const headers = Object.keys(this.apiComponent).reduce((acc, header) => {
-          acc.push({
-            level: 2,
-            text: this.$t(`api-headers.${header}`),
-            to: `#api-${header}`,
-          })
-          return acc
-        }, [])
-        this.toc.push(...headers)
-      },
     },
-
   }
 </script>