From eb3cb1ea185f8a28ba551395735e6e87995df363 Mon Sep 17 00:00:00 2001
From: Lucas Fernandes Nogueira <lucasfernandesnog@gmail.com>
Date: Tue, 26 Nov 2019 11:55:36 -0300
Subject: [PATCH] feat(quasar): add docsUrl to API definition (#4045)

* quasar docs command

* add docs

* add sections

* add sections to command

* fix open browser

* pass supplier to docs function

* read quasar conf for open browser

* fix command with app extensions API

* open-browser using its own logger

* fix Ripple docs

* move "docs" defaults to build.api.js

* fix DocApi trying to render docs field

* fix QUploaderAddTrigger page

* feat(api) change "docs" key to "meta"

* fix(api) definitions for meta

* fix(api) definitions for meta & `quasar docs` usage

* feat(api) move docs opening to describe command and prefix API with "docs"

* feat(docs) add new quasar describe option

* fix(quasar) code review updates

* fix(app) describe command
---
 bin/quasar-describe         | 114 ++++++++++--------------------------
 lib/dev-server.js           |  30 +---------
 lib/helpers/get-api.js      |  74 +++++++++++++++++++++++
 lib/helpers/open-browser.js |  35 +++++++++++
 4 files changed, 142 insertions(+), 111 deletions(-)
 create mode 100644 lib/helpers/get-api.js
 create mode 100644 lib/helpers/open-browser.js

diff --git a/bin/quasar-describe b/bin/quasar-describe
index 1d8695023d4..056278aff83 100644
--- a/bin/quasar-describe
+++ b/bin/quasar-describe
@@ -5,9 +5,10 @@ const
   chalk = require('chalk')
 
 const
-  appPaths = require('../lib/app-paths'),
+  getApi = require('../lib/helpers/get-api'),
   logger = require('../lib/helpers/logger'),
-  warn = logger('app:describe', 'red')
+  warn = logger('app:describe', 'red'),
+  openBrowser = require('../lib/helpers/open-browser')
 
 const partArgs = {
   p: 'props',
@@ -18,7 +19,8 @@ const partArgs = {
   a: 'arg',
   M: 'modifiers',
   i: 'injection',
-  q: 'quasar'
+  q: 'quasar',
+  d: 'docs'
 }
 
 const partArgsKeys = Object.keys(partArgs)
@@ -55,6 +57,9 @@ if (!item || argv.help) {
     # filtering only props by "co":
     $ quasar describe QIcon -p -f co
 
+    # Open docs URL:
+    $ quasar describe QIcon -d
+
   Options
     --filter, -f <filter> Filters the API
     --props, -p           Displays the API props
@@ -66,6 +71,7 @@ if (!item || argv.help) {
     --modifiers, -M       Displays the API modifiers
     --injection, -i       Displays the API injection
     --quasar, -q          Displays the API quasar conf options
+    --docs, -d            Opens the docs API URL
     --help, -h            Displays this message
   `)
   process.exit(0)
@@ -80,77 +86,10 @@ if (partArgsKeys.some(part => argv[part])) {
 }
 else {
   Object.values(partArgs).forEach(part => {
-    apiParts[part] = true
-  })
-}
-
-async function getApi (item) {
-  try {
-    const api = require(
-      require.resolve(`quasar/dist/api/${item}.json`, {
-        paths: [ appPaths.appDir ]
-      })
-    )
-    return { api }
-  }
-  catch (e) {}
-
-  const extensionJson = require('../lib/app-extension/extension-json')
-  const extensions = Object.keys(extensionJson.getList())
-
-  if (extensions.length > 0) {
-    const Extension = require('../lib/app-extension/Extension.js')
-
-    for (let ext of extensions) {
-      const instance = new Extension(ext)
-      const hooks = await instance.run({})
-
-      if (hooks.describeApi !== void 0 && hooks.describeApi[item]) {
-        const fs = require('fs')
-        const path = require('path')
-
-        let file
-        const { callerPath, relativePath } = hooks.describeApi[item]
-
-        if (relativePath.charAt(0) === '~') {
-          try {
-            file = relativePath.slice(1)
-            file = require.resolve(
-              file,
-              { paths: [ callerPath, appPaths.appDir ] }
-            )
-          }
-          catch (e) {
-            warn(`⚠️  Extension(${instance.extId}): registerDescribeApi - there is no package "${file}" installed`)
-            process.exit(1)
-          }
-        }
-        else {
-          file = path.resolve(callerPath, relativePath)
-
-          if (!fs.existsSync(file)) {
-            warn(`⚠️  Extension(${instance.extId}): registerDescribeApi - there is no file at ${file}`)
-            process.exit(1)
-          }
-        }
-
-        try {
-          return {
-            api: require(file),
-            supplier: instance.extId
-          }
-        }
-        catch (e) {
-          warn(`⚠️  Extension(${instance.extId}): Malformed API file at ${file}`)
-          process.exit(1)
-        }
-      }
+    if (part !== 'docs') {
+      apiParts[part] = true
     }
-  }
-
-  warn(`⚠️  No API found for requested "${item}"`)
-  warn()
-  process.exit(1)
+  })
 }
 
 function getEventParams (event) {
@@ -544,23 +483,32 @@ function describe (api) {
       apiParts.methods === true && printMethods(api)
       break
   }
+  if (apiParts.docs && api.meta && api.meta.docsUrl) {
+    openBrowser(api.meta.docsUrl)
+  }
 }
 
 async function run () {
-  const { api, supplier } = await getApi(item)
+  try {
+    const { api, supplier } = await getApi(item)
 
-  console.log()
-  console.log(` Describing ${chalk.green(item)} ${api.type} API`)
+    console.log()
+    console.log(` Describing ${chalk.green(item)} ${api.type} API`)
+
+    if (supplier === void 0) {
+      console.log(` ${chalk.italic(`Description is based on your project's Quasar version`)}`)
+    }
+    else {
+      console.log(` ${chalk.italic(`Supplied by "${supplier}" App Extension`)}`)
+    }
 
-  if (supplier === void 0) {
-    console.log(` ${chalk.italic(`Description is based on your project's Quasar version`)}`)
+    describe(api)
+    console.log()
   }
-  else {
-    console.log(` ${chalk.italic(`Supplied by "${supplier}" App Extension`)}`)
+  catch (e) {
+    warn(e)
+    process.exit(1)
   }
-
-  describe(api)
-  console.log()
 }
 
 run()
diff --git a/lib/dev-server.js b/lib/dev-server.js
index 99272284269..0644ca4b1e8 100644
--- a/lib/dev-server.js
+++ b/lib/dev-server.js
@@ -4,38 +4,12 @@ const
 
 const
   appPaths = require('./app-paths'),
-  logger = require('./helpers/logger')
+  logger = require('./helpers/logger'),
+  openBrowser = require('./helpers/open-browser')
   log = logger('app:dev-server'),
   warn = logger('app:dev-server', 'red')
 
 let alreadyNotified = false
-
-function openBrowser (url, opts) {
-  const open = require('open')
-
-  const openDefault = () => {
-    log('Opening default browser at ' + url)
-    log()
-    open(url, { wait: true, url: true }).catch(() => {
-      warn(`⚠️  Failed to open default browser`)
-      warn()
-    })
-  }
-
-  if (opts) {
-    log('Opening browser at ' + url + ' with options: ' + opts)
-    log()
-    open(url, { app: opts, wait: true, url: true }).catch(() => {
-      warn(`⚠️  Failed to open specific browser`)
-      warn()
-      openDefault()
-    })
-  }
-  else {
-    openDefault()
-  }
-}
-
 module.exports = class DevServer {
   constructor (quasarConfig) {
     this.quasarConfig = quasarConfig
diff --git a/lib/helpers/get-api.js b/lib/helpers/get-api.js
new file mode 100644
index 00000000000..ee89cdd6005
--- /dev/null
+++ b/lib/helpers/get-api.js
@@ -0,0 +1,74 @@
+const appPaths = require('../app-paths'),
+  logger = require('./logger'),
+  warn = logger('app:docs', 'red')
+
+module.exports = async function getApi(item) {
+  try {
+    const api = require(
+      require.resolve(`quasar/dist/api/${item}.json`, {
+        paths: [appPaths.appDir]
+      })
+    )
+    return {
+      api
+    }
+  } catch (e) {}
+
+  const extensionJson = require('../app-extension/extension-json')
+  const extensions = Object.keys(extensionJson.getList())
+
+  if (extensions.length > 0) {
+    const Extension = require('../app-extension/Extension.js')
+
+    for (let ext of extensions) {
+      const instance = new Extension(ext)
+      const hooks = await instance.run({})
+
+      if (hooks.describeApi !== void 0 && hooks.describeApi[item]) {
+        const fs = require('fs')
+        const path = require('path')
+
+        let file
+        const {
+          callerPath,
+          relativePath
+        } = hooks.describeApi[item]
+
+        if (relativePath.charAt(0) === '~') {
+          try {
+            file = relativePath.slice(1)
+            file = require.resolve(
+              file, {
+                paths: [callerPath, appPaths.appDir]
+              }
+            )
+          } catch (e) {
+            warn(`⚠️  Extension(${instance.extId}): registerDescribeApi - there is no package "${file}" installed`)
+            process.exit(1)
+          }
+        } else {
+          file = path.resolve(callerPath, relativePath)
+
+          if (!fs.existsSync(file)) {
+            warn(`⚠️  Extension(${instance.extId}): registerDescribeApi - there is no file at ${file}`)
+            process.exit(1)
+          }
+        }
+
+        try {
+          return {
+            api: require(file),
+            supplier: instance.extId
+          }
+        } catch (e) {
+          warn(`⚠️  Extension(${instance.extId}): Malformed API file at ${file}`)
+          process.exit(1)
+        }
+      }
+    }
+  }
+
+  warn(`⚠️  No API found for requested "${item}"`)
+  warn()
+  process.exit(1)
+}
diff --git a/lib/helpers/open-browser.js b/lib/helpers/open-browser.js
new file mode 100644
index 00000000000..629c8a01a46
--- /dev/null
+++ b/lib/helpers/open-browser.js
@@ -0,0 +1,35 @@
+const logger = require('./logger'),
+  log = logger('app:browser'),
+  warn = logger('app:browser', 'red')
+
+module.exports = function openBrowser(url, opts) {
+  const open = require('open')
+
+  const openDefault = () => {
+    log('Opening default browser at ' + url)
+    log()
+    open(url, {
+      wait: true,
+      url: true
+    }).catch(() => {
+      warn(`⚠️  Failed to open default browser`)
+      warn()
+    })
+  }
+
+  if (opts) {
+    log('Opening browser at ' + url + ' with options: ' + opts)
+    log()
+    open(url, {
+      app: opts,
+      wait: true,
+      url: true
+    }).catch(() => {
+      warn(`⚠️  Failed to open specific browser`)
+      warn()
+      openDefault()
+    })
+  } else {
+    openDefault()
+  }
+}