From 977c1c06dc1024448a181e17dc7de727b7c6a19f Mon Sep 17 00:00:00 2001
From: Michael Krotscheck <krotscheck@gmail.com>
Date: Tue, 23 Aug 2016 14:48:25 -0700
Subject: [PATCH] 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                             |  2 +-
 doc/source/index.rst                   |  2 ++
 doc/source/reference_documentation.rst | 12 ++++++++++++
 package.json                           |  5 +++--
 4 files changed, 18 insertions(+), 3 deletions(-)
 create mode 100644 doc/source/reference_documentation.rst

diff --git a/.gitignore b/.gitignore
index a418b95..9715d30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,4 +19,4 @@ pids
 reports
 www
 doc/build
-jsdoc_build
+doc/source/jsdoc
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6c99196..601ee3d 100644
--- a/doc/source/index.rst
+++ b/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
diff --git a/doc/source/reference_documentation.rst b/doc/source/reference_documentation.rst
new file mode 100644
index 0000000..23bd27d
--- /dev/null
+++ b/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-*
diff --git a/package.json b/package.json
index 859a7df..5e1f35e 100644
--- a/package.json
+++ b/package.json
@@ -9,8 +9,8 @@
     "posttest": "istanbul check-coverage",
     "prepublish": "nsp check",
     "lint": "eslint ./",
-    "docs": "(cd doc; make html)",
-    "jsdoc": "jsdoc generators/app/lib -r -d jsdoc_build"
+    "docs": "npm run jsdoc; (cd doc; make html)",
+    "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",