Documentation for the modules generated from their source will appear on this Web site as it becomes available. Since the implemenation language of choice is Python, doc extractors are being deployed such as Pythondoc, HappyDoc or Epydoc, Pythondoc being the tool currently in use (The Epydoc Web site has a fairly up-to-date overview of available doc extractors for Python).

First of all, you have to put documentation comments into your source code . There is an online description of the formats and recognised tags. Basically, it is a Javadoc-like tag and comment style. Start your comments with two pound signs (##) on an own row, then continue with single pound signs. Only the module comment, the first comment of this kind encountered in a file, has to be closed with another line of two pound signs. In this manner, modules, classes, functions and variables can be documented.

HTML in the documentation strings is allowed. Make sure to escape double quotes in your doc comments (\”), or your documenation will not be usable with the API Viewer as explained in the next section.

After that you can extract your documenation with Pythondoc like this:

pythondoc.py <file>.py

Use qooxdoo’s pythondoc.py (it’s patched), not the one from the Internet. The resulting HTML will be printed to STDOUT and can be redirected. As an interesting detail, pythondoc allows you to specify a style-sheet to be used in the HTML:

pythondoc.py -Dstyle=http://some.server/some/style.css <file>.py

The API viewer is an exciting app and features various qooxdoo packages. The aim of this section is to include the source documentation of qooxdoo’s Python modules with the API viewer. This is currently a three-step process:

• Extract the documentation from the Python source code into XML format.
• Transform this XML into the qooxdoo XML format suitable for the API viewer.
• Transform the qooxdoo XML into the JSON data structur which can be used by the API viewer app as input data.

Use qooxdoo’s pythondoc.py (it’s patched), not the one from the Internet.

pythondoc.py -x <file>.py > pythondoc.xml

(The output re-direction doesn’t work currently, I need to fix this. Currently, a pythondoc-<filename>.xml file will be generated).

Using the style-sheet pydoc2qx-xml.xsl you transform the Pythondoc XML into a qooxdoo-style XML.

xsltproc pydoc2qx-xml.xsl pythondoc.xml > qx-xml.xml

The validity of the resulting XML can be checked against a schema (e.g. qx-xml.rng), using a validator like xmllint: xmllint –relaxng qx-xml.rng –noout qx-xml.xml.

Schema conversions, e.g. from DTD to RelaxNG, can be performed by a tool such as trang: java -jar ~/lib/java/trang.jar qx-xml.dtd qx-xml.rng.

The resulting qx-xml.xml is an XML fragment in the sense that it lacks the top-most enclosing elements, ‘<doctree>’ and ‘<packages>’, to be fully compatible with the API Viewer. (The XML file as it is still works, but not as nicely).

To amend for that you need to wrap the contents of the XML file with a pair of the top-level tags:

<doctree>
  <packages>
  
  . . . (generated XML goes in here)

  </packages>
</doctree>

But this also allows you run the pydoc2qx-xml.xsl on multiple files, concatenating the output into a single result file, and then put in the wrapping top-level elements, this way creating a single documentation file for the next processing step.

The third step will then generate a JSON data file from the qooxdoo XML that is suitable to be used with the API Viewer. You just apply the style-sheet qx-xml2qx-json.xls to the XML file obtained in the previous step:

xsltproc qx-xml2qx-json.xslt qx-xml.xml > apidata1.js

The apidata1.js is now usable with the API Viewer. If you have a running API Viewer, go to its installation directory, exchange the apidata.js file and reload the API Viewer in your browser (you might want to make a backup copy of the original apidata.js file first):

cd application/apiviewer/source/script
cp apidata.js apidata.js.bak
cp apidata1.js apidata.js

Reload the API Viewer in your browser and you should see the Pythondoc documentation for the modules you’ve just created.

There is currently no integration of the Python documentation and the JavaScript documentation, so you just have to swap files to switch between the two documentation sets.