Asterias | Main / DevelopersDocumentation

Documentation

For now, the main documentation is this 2-page pdf, presented at the useR2006 conference. The Graphviz dot sources for the figures, the LaTeX source for the pdf, and a "wikified" version will be coming soon.

A (messy) graph of file dependencies and function calls

To help navigate the code, you can get a pdf or svg (or the original dot) file showing where functions are defined, from which files are functions called, and which libraries/imports/includes are used in the different files. Here is the legend for the figures, as pdf or svg or the original dot file.

The figures of the calls (not the legend) are very large (and that is why we do not provide a png). Note that the pdf might be searchable, if your pdf viewer supports it; for instance, try using acrobat reader and searching for nnhl.c. But the SVG might be more convenient, and easier to modify at will. Inkscape, for example, is an excellent SVG drawing program, that runs under Linux, Windows and MacOSX, and allows to search for text.

To produce these figures, we used a small Python program that generates a dot file, and then calls Graphviz. You can get the program here; it should be easy to adapt to other setups. (But I do not know if it will run under windows, or whether the programs it calls are available for windows). The above Python program itself calls exuberant ctags (to find all function definitions, all includes, etc) and idutils (the mkid program) to tokenize all the files. To tokenize Python and R files, we patched idutils (see details and links to downloads here); for exuberant ctags we used a patch for R.

Style Guide

We haven't followed any uniform coding style, but we should. The Style Guide for Python Code should be adhered to for all new Python code. For R code, see the R coding standards.

Using FunkLoad for testing

We are using FunkLoad as our main testing tool. Why? In fact, there are a variety of other testing tools in Python; for instance, see the links at Twill's site. One of the many things we like about FunkLoad is that it can deal with JavaScript. That is an important feature for us, for example with Pomelo II (and, progressively, for other applications), that uses javaScript heavily. It is true that, for many cases, using FunkLoad feels "too heavy", such as when testing the numerical output, and all you need is to submit a file, and get back the output for further processing. For these cases, for instance, Twill is very attractive, but the lack of JavaScript support can be for us a show stopper.