SVG and Code Documentation

Return home.

Contents

A personal project that explored ideas in code documentation; the prettiest involving SVG.

Architecture

This was web based, using Python on the server (Django). The code to be documented (also Python) was parsed to extract dependencies (down to the level of classes and functions, although only modules were displayed) - the data were stored in a PostgreSQL database.

The SVG was generated on the client - Javascript parsed a compact description of the data to be displayed (loaded on demand from a web service) and generated the appropriate SVG elements. The Google SVG shim simplified cross-platform support.

Screenshots

Front page / lepl dependencies

Front page / lepl dependencies

This shows the main screen, with the dependency plot for the entire Lepl package. The circular arcs (mainly red) are the different modules; the innner arcs (mainly black) show the dependencies between modules.

The “Projects” and “Site” tabs (top right) were slide-down menus (implemented with YUI-3) for navigation and configuration.

Mousing over lepl.matchers arc (detail to right)

Mousing over lepl.matchers arc (detail to right)

Moving the cursor over an arc highlights the dependencies for that module. The details are listed to the right, as links.

Clicking on a link displayed source code:

Source code with pylint warning

Source code with pylint warning

The source is augmented with simple syntax-based highlights and pylint warnings (displayed when the mouse movers over the marker, as shown above).

Score over time (detail to right)

Score over time (detail to right)

Integration with pylint extended to including the “code quality score” and related statistics (accessed via the “statistics” tab seen on the first screenshot).

The graph - implemented with SVG - can be zoomed and panned with the mouse. Colour-coding indicated whether the score had improved (green) or deteriorated (red).

Lessons Learned

Positive

I gained a lot more experience with complex client code - an area that I rarely work on in my paid work.

Negative

This was a significant investment of time, but didn’t produce a useful “final product”. It was fun exploring a bunch of new ideas, and I gained a lot of experience in complex Javascript / SVG work, but a less ambitious, more focussed approach might have made something more lasting.

Also, while the dependency plot was very eye-catching (particularly when responding to mouse movement across arcs), it wasn’t that useful.