Added jsdoc3 output to doc generation

This patch adds jsdoc3-generated documentation to our docs build.
It does so by using publicly available sphinx.rst templates, writing
them into a .gitignore'd folder in the docs directory, and providing
references to these autogenerated documents in our own site.

There are some notable bugs:
- jsdoc-sphinx templates do not honor @ignore and @private
- jsdoc-sphinx templates do not ignore private variables (listed under
  members at the bottom).
- jsdoc-sphinx templates add superfluous 'Children' section to the
  top as subsection navigation.

It would make quite a bit of sense for us to contribute to
jsdoc-sphinx so that the above mentioned bugs are resolved. However,
as some documentation is better than no documentation, right now this
is fine.

Change-Id: I2905358a6410d5dace96c25dc57dda100fae4b48

.gitignore

@@ -42,3 +42,4 @@ clouds.yaml
 
 # Doc build
 doc/build
+doc/source/jsdoc

doc/source/index.rst

@@ -15,6 +15,7 @@ Topics
    :maxdepth: 2
 
    getting_started
+   reference_documentation
    dev_get_started
    specs
 

doc/source/reference_documentation.rst

@@ -0,0 +1,11 @@
+=======================
+Reference Documentation
+=======================
+
+Below you will find reference documentation for individual components of the JavaScript SDK. For
+detailed, method-specific documentation, select the appropriate method below.
+
+.. toctree::
+   :maxdepth: 2
+
+   jsdoc/Keystone

package.json

@@ -15,7 +15,8 @@
     "lint": "eslint ./",
     "prepublish": "nsp check; npm run build",
     "build": "babel src -d dist && webpack",
-    "docs": "(cd ./doc && make html)"
+    "docs": "npm run jsdoc; (cd ./doc && make html)",
+    "jsdoc": "jsdoc -t node_modules/jsdoc-sphinx/template -d ./doc/source/jsdoc ./src"
   },
   "repository": {
     "type": "git",
@@ -45,6 +46,8 @@
     "jasmine": "^2.4.1",
     "jasmine-core": "^2.4.1",
     "js-yaml": "^3.6.1",
+    "jsdoc": "^3.4.0",
+    "jsdoc-sphinx": "0.0.6",
     "json-loader": "^0.5.4",
     "karma": "^1.1.1",
     "karma-chrome-launcher": "^1.0.1",

src/keystone.js

@@ -3,7 +3,8 @@ import Http from './util/http';
 /**
  * A list of all supported versions. Please keep this array sorted by most recent.
  *
- * @type {Array} An array of version instances.
+ * @type {Array}
+ * @ignore
  */
 const supportedKeystoneVersions = [
   'v3.7'
@@ -11,6 +12,16 @@ const supportedKeystoneVersions = [
 
 export default class Keystone {
 
+  /**
+   * This class provides direct, idempotent, low-level access to the Keystone API of a specific
+   * cloud. The constructor requires that you provide a configuration object for a specific
+   * cloud, formatted as per the os-client-config specification of clouds.yaml. An important
+   * difference is that it does not accept the entire clouds.yaml structure, only the subsection
+   * that refers to a specific cloud.
+   *
+   * @param {{}} cloudConfig The configuration object for a specific cloud.
+   * @see http://docs.openstack.org/developer/os-client-config/#site-specific-file-locations
+   */
   constructor (cloudConfig) {
     // Sanity checks.
     if (!cloudConfig) {
@@ -29,6 +40,7 @@ export default class Keystone {
    * @param {string} path A string representing the dot notation of a config path to read.
    * @private
    * @returns {String} The value found in the config, or null.
+   * @ignore
    */
   _safeConfigGet (path) {
     let segments = path.split('.');