JsDoc Toolkit RST-Template

Project provides a RST (ReStructuredText) compliant templates for JsDoc Toolkit documentation generator, making it easy to document project’s JavaScript resources with Sphinx.

With the custom rst -template, it is possible to generate rst-document pages using JsDoc Toolkit. From there, the generated pages can be included as part of documentation, similar to Sphinx autogen feature. The process is shown in the illustration:

_images/process.png

Installation

Suggested installation steps (unless you already have some of the apps/modules installed)

  1. Install Java and Ant:

  2. Install JsDoc Toolkit:

  3. Setup JsDoc Toolkit RST Template

    • Download the package (not yet available) or checkout the sources:

    • Open build.properties for editing and set the directories:

      • Where to find JsDoc Toolkit
      • Where to read javascript sources
      • Where to generate rst documents
      # Directory where the jsdoc-toolkit is installed
jsdoc-toolkit.dir=/opt/jsdoc-toolkit

# Directory where to find javascript sources
js.src.dir=src/js

# Directory where to generate rst files
js.rst.dir=dist/rst

      Tip

      You can also pass these values as a parameter to Ant:

      ant -Djs.src.dir=somewhere/else build

  4. Test the setup to ensure everything works:

    • List Ant tasks:

      ant -p

    • Try out the js conversion by building the .js -sources:

      ant build

    • See the outcode directory defined by js.rst.dir

Note

This document only describes how to generate RST-files from JavaScript -sources. Please follow the Sphinx -official documentation for how to write and configure documentation.

Usage

As it can be seen from the illustration, generating the JavaScript -source API into Sphinx powered documentation, it requires a tool chain:

Comment your code

Javascript source code, commented using JsDoc Toolkit commenting conventions.

/**
* @class
* Comment block
*
* @param {string} name Unique name for the app
*/
var App = function (name) {
  // @default "Anonymous"
  this.name = name || 'Anonymous';
};

/**
 * Runs the app
 * @returns {App} itself bac
 */
App.run = function() {
  return this;
}

Generate API documents

Build RST documents from source code with either directly with JSDoc Toolkit or Ant script:

ant -Djs.src.dir=src/myapp -Djs.rst.dir=doc/api/myapp  build

After generating the source code with custom template, the outcome is something like (in this case, the file name is api/myapp/symbols/App.rst):

.. js:class:: App (name)

    Comment block

    :param string name:

       Unique name for the app

    .. js:function:: App.run ()

       Runs the app

Note

You may edit the generated RST API documents, if you like. However, that prevents you re-generating the documents from the sources again (unless you are willing to do some manual merging). Which approach you should use, depends on needed documentation.

Write documentation

Now, both generated and manually written documentation can be used together. The documentation structure may be as follows:

conf.py
index.rst
api/
  index.rst
  symbols/
    _global_.rst
    App.rst

To include API documents in Sphinx document tree, the suggested method is to set api/index -toctree somewhere in master document:

.. toctree::

   api/index

Then, you may refer documented classes, functions and other JavaScript elements by using Sphinx notation:

The application is implemented in class :js:class:`App`,
where as the actual processing is done in :js:func:`App.run`.
To see the complete API, see :ref:`separate API document <api>`.

Examples

Following documents are generated using the RST template:

License: MIT

This piece of software is MIT licensed. It means you can freely take it, hack it and break it - both in personal and commercial use.

This also means your contribution is welcome