Navigation

Whereas in Python source code we only need to include a module docstrings
using the directive .. automodule:: mypythonmodule, we will have to
explicitely define Javascript modules and functions in the doctrings since
there is no native directive to include Javascript files.

pyjsrest is a small utility parsing Javascript doctrings and generating the
corresponding Restructured file used by Sphinx to generate HTML documentation.
This script will have the following structure:

===========filename.js===========..module::filename.js

We use the .. module:: directive to register a javascript library
as a Python module for Sphinx. This provides an entry in the module index.

The contents of the docstring found in the javascript file will be added as is
following the module declaration. No treatment will be done on the doctring.
All the documentation structure will be in the docstrings and will comply
with the following rules.

We will define function parameters as a bulleted list, where the
parameter name will be backquoted and followed by its description.

Example of a javascript function docstring:

.. function:: loadxhtml(url, data, reqtype, mode)
cubicweb loadxhtml plugin to make jquery handle xhtml response
fetches `url` and replaces this's content with the result
Its arguments are:
* `url`
* `mode`, how the replacement should be done (default is 'replace')
Possible values are :
- 'replace' to replace the node's content with the generated HTML
- 'swap' to replace the node itself with the generated HTML
- 'append' to append the generated HTML to the node's content

Javascript functions handle arguments not listed in the function signature.
In the javascript code, they will be flagged using /* … */. In the docstring,
we flag those optional arguments the same way we would define it in
Python: