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
This commit is contained in:
Michael Krotscheck 2016-08-23 14:48:25 -07:00 committed by Yujun Zhang
parent 95bd3089bb
commit 977c1c06dc
4 changed files with 18 additions and 3 deletions

2
.gitignore vendored
View File

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

View File

@ -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

View File

@ -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-*

View File

@ -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",