Documenting javascript

Sandrine and Alain worked on the javascript documentation tools and how they could be integrated into our sphinx generated documentation.

They first studied pyjsdoc which unfortunately only generates HTML. After a somewhat successful attempt to generate sphinx ReST, we decided to use a consistent documentation format between python modules and js modules and therefore switched to a home-made, very simple javascript comment parser. Here's an example of what the parser understands:

/**
 * .. cfunction:: myFunction(a, b, /*...*/, c, d)
 *
 *    This function is very **well** documented and does quite
 *    a lot of stuff :
 *    - task 1
 *    - task 2
 *
 *    :param a: this is the first parameter
 *    ...
 *    :return: 42
 */
function myFunction(a, b, /*...*/, c, d) {
}

The extracted ReST snippets are then concatenated and inserted in the general documentation.

Unit testing javascript

Katia, Julien and Adrien looked at the different testing tools for javascript, with the two following goals in mind:

• low-level unit testing, as cubicweb agnostic as possible
• high-level / functional testing, we want to write navigation scenarios and replay them

And the two winners of the exploration are:

• QUnit for pure javascript / DOM testing. Julien and Adrien successfully managed to test a few cubicweb js functions, most notably the loadxhtml jquery plugin.
• Windmill for higher level testing. Katia and Sylvain were able to integrate Windmill within the CubicWeb unit testing framework.

Of course, there is still a lot of work that needs to be done. For instance, we would like to have a test runner facility to run QUnit-based tests on multiple platforms / browsers automatically.

Parametrized stylesheets and vertical rhythm

Sylvain worked on property sheets and managed to implement compiled CSS based on simple string interpolation. Of course, compiled CSS are still HTTP cached, automatically recompiled on debug mode, etc. On his way, he also got rid of the external_resources file. Backward compatibility will of course be guaranteed for a while.

Nicolas worked on CSS and vertical rythm and prepared a patch that introduces a basic rhythm. The tedious work will be to get every stylesheet to dance to the beat.