Skip to content

juhamust/jsdoc-toolkit-rst-template

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Juha Mustonen
Aug 13, 2014
6512a0a · Aug 13, 2014

History

6 Commits
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014
Aug 13, 2014

Repository files navigation

jsdoc-toolkit-rst-template

Project provides a RST (ReStructuredText) compliant templates for JsDoc-Toolkit documentation generator, making it easy to document JavaScript project 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.

https://raw.githubusercontent.com/juhamust/jsdoc-toolkit-rst-template/develop/doc/process.png

Table of contents

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

  1. Install Java and Ant:

    • Download Java and extract it for example to /opt/java/
    • Download Ant and extract it for example to /opt/apache-ant/
  2. Install JsDoc Toolkit:

  3. Setup JsDoc Toolkit RST Template (this project):

    • Checkout the sources (package will be available as soon as 0.1 is out)

    • 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
        
  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.

Template can be used normally with jsdoc-tookit:

java -Djsdoc.dir=/path/to/jsdoc-toolkit -Djsdoc.template.dir=/path/to/rst/template \
-jar /path/to/jsdoc-toolkit/jsrun.jar /path/to/jsdoc-toolkit/app/run.js [SRCDIR/SRCFILE]

However, this project also comes with Ant script file that can be used for compiling JavaScript files into RST - and into html/pdf/whatever with Sphinx:

ant build
ant doc

Javascript source code, commented using jsdoc-toolkit keywords:

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

After generating the source code with custom template, the outcome is something like:

.. js:class:: App (name)

    Comment block

    :param string name:

        Unique name for the app

Now, both generated and manually written documentation can be used together.

The application is implemented in class :js:class:`App`. To see the complete API, see :ref:`separate API document <api>`

Your contribution to the project is very welcome! Here are some instructions how to get started with the development environment:

Documentation
  1. Install python

  2. Install ruby and related modules (needed only previewing README.rst outcome)

    # install ruby gem install bundler bundle install

  3. Build README.rst (into README.html)

    ./build.rb

About

ReStructuredText template for JavaScript API documentation toolkit

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published