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: Ie7503f4874c8b4bbb4bb4926cddc578d59ce0613

.gitignore

@@ -19,4 +19,4 @@ pids
 reports
 www
 doc/build
-jsdoc_build
+doc/source/jsdoc

doc/source/index.rst

@@ -43,6 +43,8 @@ Topics
 
      development_guide
      specs
+     reference_documentation
+
 
 .. _StoryBoard: https://storyboard.openstack.org/#!/project/842
 .. _gerrit: https://review.openstack.org/#/q/status:open+AND+project:openstack/js-generator-openstack,n,z

doc/source/reference_documentation.rst

@@ -0,0 +1,12 @@
+=======================
+Reference Documentation
+=======================
+
+Below you will find reference documentation for individual components of the generator. For
+detailed, method-specific documentation, select the appropriate method below.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   jsdoc/module-*

package.json

@@ -9,8 +9,8 @@
     "posttest": "istanbul check-coverage",
     "prepublish": "nsp check",
     "lint": "eslint ./",
-    "docs": "(cd doc; make html)",
+    "docs": "npm run jsdoc; (cd doc; make html)",
-    "jsdoc": "jsdoc generators/app/lib -r -d jsdoc_build"
+    "jsdoc": "jsdoc -t node_modules/jsdoc-sphinx/template -r -d ./doc/source/jsdoc ./generators/app/lib"
   },
   "keywords": [
     "yeoman-generator",
@@ -36,6 +36,7 @@
     "istanbul": "^0.4.2",
     "jasmine": "^2.4.1",
     "jsdoc": "^3.4.0",
+    "jsdoc-sphinx": "0.0.6",
     "karma": "^0.13.22",
     "karma-htmlfile-reporter": "^0.2.2",
     "mem-fs": "^1.1.2",