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:
parent
95bd3089bb
commit
977c1c06dc
|
@ -19,4 +19,4 @@ pids
|
|||
reports
|
||||
www
|
||||
doc/build
|
||||
jsdoc_build
|
||||
doc/source/jsdoc
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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-*
|
|
@ -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",
|
||||
|
|
Loading…
Reference in New Issue