Overhaul code documentation

Author: eFrane

docs/.vuepress/config.js

@@ -23,7 +23,7 @@ module.exports = {
       '/usage/',
       '/usage/modules.html',
       '/usage/requests.html',
-      '/code/'
+      '/code/classes/'
     ]
   },
   evergreen: true

docs/.vuepress/jsdoc.js

@@ -0,0 +1,97 @@
+// YARN_SILENT=1 yarn jsdoc2md -f 'src/**/*' --private -l js --name-format --separators --template docs/.vuepress/jsdoctemplate.handlebars > docs/code/README.md
+const fs = require('fs')
+const path = require('path')
+const jsdoc2md = require('jsdoc-to-markdown')
+const handlebars = require('handlebars')
+
+
+function loadTemplate (templateName) {
+  const relativeTemplateName = `docs/.vuepress/templates/jsdoc/${templateName}.handlebars`
+  if (fs.existsSync(relativeTemplateName)) {
+    const templateData = fs.readFileSync(relativeTemplateName, { encoding: 'utf-8' })
+    return handlebars.compile(templateData)
+  }
+
+  return null
+}
+
+handlebars.registerHelper('jsDocBlock', function () {
+  const template = loadTemplate(`kind.${this.kind}`)
+  if (template) {
+    return template(this)
+  }
+
+  return `**MISSING JSDOC TEMPLATE FOR DOC BLOCK KIND ${this.kind}**`
+})
+
+const dirs = ['classes', 'functions']
+dirs.forEach(dir => {
+  const relDir = `docs/code/${dir}`
+  if (!fs.existsSync(relDir))
+  fs.mkdirSync(relDir)
+})
+
+const templateData = jsdoc2md.getTemplateDataSync({
+  files: path.resolve('src/**/*.js')
+})
+
+documentClasses(templateData)
+// documentFunctions(templateData)
+
+/**
+ *
+ * @param {Object} templateData
+ */
+function documentClasses (templateData) {
+  const classes = templateData.reduce((classNames, identifier) => {
+    if (identifier.kind === 'class') classNames.push(identifier.name)
+    return classNames
+  }, [])
+
+  const classTemplate = loadTemplate('class')
+
+  const classIndexData = {
+    classes: {}
+  }
+
+  for (const cls of classes) {
+    classIndexData.classes[cls] = {
+      name: cls,
+      link: cls + '.html'
+    }
+  }
+
+  console.log(classIndexData)
+
+  classes.forEach(className => {
+    const fileName = `docs/code/classes/${className}.md`
+    const classData = templateData
+      .filter(jsdocBlock => jsdocBlock.memberof === className)
+      .sort((a, b) => {
+        return a.order < b.order ? -1 : 1
+      }).forEach(classData => {
+        if (classData.kind === 'class') {
+          classIndexData.classes[className].description = classData.description
+        }
+      })
+
+    console.log(`rendering ${className} to ${fileName}`)
+    fs.writeFileSync(fileName, classTemplate({ className, classData }))
+  })
+
+  console.log('rendering index for class documentation')
+  fs.writeFileSync('docs/code/classes/README.md', loadTemplate('classindex')(classIndexData))
+}
+
+/**
+ *
+ * @param {Object} templateData
+ */
+function documentFunctions (templateData) {
+  const functionNames = templateData.reduce((functionNames, identifier) => {
+    if (identifier.kind === 'function') functionNames.push(identifier.name)
+    return functionNames
+  }, [])
+
+  console.dir(functionNames)
+}

docs/.vuepress/jsdoctemplate.handlebars

@@ -1,3 +1,8 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
 # API
 
 {{>main}}

docs/.vuepress/templates/jsdoc/class.handlebars

@@ -0,0 +1,12 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class {{ className }}
+
+{{#each classData}}
+{{ jsDocBlock }}
+{{/each}}
+
+__This is an autogenerated class documentation for {{ className }} __

docs/.vuepress/templates/jsdoc/classindex.handlebars

@@ -0,0 +1,9 @@
+# Available Classes
+
+{{#each classes}}
+## {{ name }}
+
+{{{ description }}}
+
+<a href="{{ link }}">{{ name }}</a>
+{{/each}}

docs/.vuepress/templates/jsdoc/kind.class.handlebars

@@ -0,0 +1 @@
+{{{ description }}}

docs/.vuepress/templates/jsdoc/kind.constructor.handlebars

@@ -0,0 +1,3 @@
+## {{ id }}
+
+{{ description }}

docs/code/.gitignore

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class Builder
+
+
+__This is an autogenerated class documentation for Builder __

docs/code/classes/Builder.md

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class FosJsRoutingRouter
+
+
+__This is an autogenerated class documentation for FosJsRoutingRouter __

docs/code/classes/FosJsRoutingRouter.md

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class JsonApiRouter
+
+
+__This is an autogenerated class documentation for JsonApiRouter __

docs/code/classes/JsonApiRouter.md

@@ -0,0 +1,90 @@
+# Available Classes
+
+## Builder
+
+JsonApi-based module builder for Vuex
+
+This module builder will create a vuex module based on the assumption of
+working with valid json api resources.
+
+- the proposed json api 1.1 pagination style meta attributes
+  (-> https://jsonapi.org/format/1.1/#fetching-pagination)
+
+<a href="Builder.html">Builder</a>
+## FosJsRoutingRouter
+
+Pluggable api router if you're using Symfony and the FosJsRouting Bundle
+
+<a href="FosJsRoutingRouter.html">FosJsRoutingRouter</a>
+## JsonApiRouter
+
+A simple router implementation querying a json:api endpoint which delivers all
+necessary route information
+
+The endpoint must return a list of Route objects:
+
+```json
+{
+    "data": [
+        {
+            "type": "Route",
+            "id": "api.route.list",
+            "attributes": {
+                "parameters": [],
+                "url": "api/route",
+                "method": "list"
+            }
+       },
+       {
+           "type": "Route",
+           "id": "api.route.get",
+           "attributes": {
+               "parameters": [
+                   "id"
+               ],
+               "url": "api/route/{id}",
+               "method": "get"
+           }
+       }
+    ]
+}
+```
+
+To initialize this router, simply `new` it with the desired fetch path,
+e.g. `new JsonApiRouter('/api/route')`.
+
+<a href="JsonApiRouter.html">JsonApiRouter</a>
+## Route
+
+
+
+<a href="Route.html">Route</a>
+## Router
+
+Basic router implementation for the ResourcefulApi.
+
+Automagically creating api bound modules builds on
+an understanding of the available routes. To
+easily instantiate a Store bound to an endpoint,
+route information for that endpoint must be provided.
+
+Since every endpoint is implemented differently and
+the choice where this route information comes from
+should be left to the endpoint developer, this
+library only assumes that route loading is usually an
+asynchronous process which eventually returns and
+has a set of keyed-by-name `Route` objects in
+`this.routes`.
+
+<a href="Router.html">Router</a>
+## StaticRouter
+
+Static router
+
+It may be desirable to not do an additional request
+for getting the api routes and instead bake them into
+the code. To this avail, the `StaticRouter` can be
+initialized with a POJO of { id, url, parameters }
+whereas parameters are parts of the url which can be replaced.
+
+<a href="StaticRouter.html">StaticRouter</a>

docs/code/classes/README.md

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class Route
+
+
+__This is an autogenerated class documentation for Route __

docs/code/classes/Route.md

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class Router
+
+
+__This is an autogenerated class documentation for Router __

docs/code/classes/Router.md

@@ -0,0 +1,9 @@
+---
+sidebar: auto
+displayAllHeaders: true
+activeHeaderLinks: true
+---
+# Class StaticRouter
+
+
+__This is an autogenerated class documentation for StaticRouter __

docs/code/classes/StaticRouter.md

@@ -13,9 +13,9 @@
     "test": "yarn unit",
     "tdd": "yarn unit --watch",
     "lint": "eslint --ext .js,.vue src test/unit",
-    "vuepress:apidoc": "YARN_SILENT=1 yarn jsdoc2md -f 'src/**/*' --private -l js --name-format --separators --template docs/.vuepress/jsdoctemplate.handlebars > docs/code/README.md",
-    "vuepress:dev": "yarn vuepress:apidoc && vuepress dev docs",
-    "vuepress:build": "yarn vuepress:apidoc && vuepress build docs"
+    "prepublish": "node docs/.vuepress/jsdoc.js",
+    "vuepress:dev": "vuepress dev docs",
+    "vuepress:build": "vuepress build docs"
   },
   "dependencies": {
     "axios": "^0.*",
@@ -49,6 +49,7 @@
     "eslint-plugin-promise": "^3.4.0",
     "eslint-plugin-standard": "^3.0.1",
     "eslint-plugin-vue": "^4.0.0",
+    "handlebars": "^4.1.2",
     "husky": "^2.4.0",
     "jest": "^22.0.4",
     "jest-serializer-vue": "^0.3.0",