The auto JavaScript documentation Sphinx extension
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc
sphinxcontrib
MANIFEST.in
README.rst
setup.cfg
setup.py
tox.ini

README.rst

Auto JavaScript Documentaion

Author: Heungsub Lee <h@subl.ee>

This extension generates a reference documentation from a JavaScript source file. A JavaScript source code should follow the style that is suggested by jDoctest.

Installation

Enter the sphinxcontrib-autojs directory and run:

$ python setup.py install

Usage

Here is an example JavaScript source.

var ImageFile = function( url ) {
    /**class:ImageFile( url )

    A container for an image file.
        >>> var img = new ImageFile( "_static/jdoctest.png" );
        >>> img.url;
        '_static/jdoctest.png'
    */
    this.url = String( url );
};
ImageFile.prototype = {
    fetchData: function() {
        /**:ImageFile.prototype.fetchData()

        Request to the server to get data of this image file. When the
        request done we can get ``size`` or ``modified`` attribute.

            >>> img.fetchData();
            >>> wait(function() { return img.data; });
            >>> img.size;
            21618
            >>> img.modified; //doctest: +SKIP
            Sat Sep 25 2010 19:57:47 GMT+0900 (KST)
        */
        $.get( this.url, function( data ) {
            this.data = data;
            this.size = data.length;
            this.modified = new Date(); // Not Implemented Yet
        });
    }
};

The file that has this source named imagefile.js. It is in _examples directory of the current Sphinx document directory. Then this source:

.. autojs:: _examples/imagefile.js

is rendered as:

.. autojs:: _examples/imagefile.js


JavaScript Docstring

Here is the documentation of jDoctest which explains a JavaScript comment block for docstring.

A docstring is a multiline comment but it starts with /**.

But this extension examines only named docstrings. A name of a docstring is after /** and starts with ::

/**:SomeClass.prototype.someMethod( reqArg[, optArg1[, optArg2 ] ] )

The description for ``someMethod``.
*/

Then the example docstring's name is SomeClass.prototype.someMethod( reqArg[, optArg1[, optArg2 ] ] ).

JavaScript Doctest

You might know doctest module for Python. This module examines interactive Python sessions such as:

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> [factorial(long(n)) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000L

The interactive JavaScript sessions are similar to the Python's:

>>> var title = $( "h1" );
>>> title.click(function() {
...     alert( this.innerText );
... });
[object Object]
>>> Math.round( 1.11111111 );
1

Options

:members::

The member list in the source code. Each members are separated by a comma(,). A member is such as ImageFile or ImageFile.prototype.fetchData. If you want to make a documentation of only ImageFile.prototype.fetchData then:

.. autojs:: _examples/imagefile.js
   :members: ImageFile.prototype.fetchData