ITK Sphinx Examples Part I: Credits via GitStats

Studying examples is an excellent way to learn, especially for scientific software.  An example demonstrates explicitly how a concept works or how a given objective can be achieved. When code is coupled with documentation, all the critical details, which are difficult to encapsulate in prose, are immediately evident.

Following on the outstanding work by lead David Doria and Bill Lorensen with the highly successful ITK and VTK Wiki Examples, an effort was made to improve the documentation technology for examples. The base platform for the new examples is the Sphinx documentation generation system.

The Sphinx tool was originally developed to be the native documentation system for the Python programming language, but it has been widely adopted by many other software documentation efforts, including projects in languages like C++. Sphinx documentation is written in a simple, easy to read and write markup language called reStructuredText. Content in plain text reStructuredText input can be rendered into a variety of output formats, such as HTML, PDF, man pages, ePUB, etc. Sphinx has many nice features such as LaTeX equation rendering, code syntax highlighting, elegant output, quick search, extensive cross-referencing and index generation, and it is very extensible.

This is the first in a series of articles that describes how Sphinx has been extended to create a powerful example documentation system, the ITK Sphinx Examples.

The first feature to discuss is also one of the most important: automated, data-rich, visible acknowledgements via GitStats. Since examples are developed in a Git repository, they automatically retain all the benefits of distributed version control. One these benefits is authorship metadata, including author name, email, commit times, and commit line changes.

This metadata is analyzed with the popular GitStats tool. Community member Arnaud Gelas created an output generator for GitStats that creates reStructuredText.  The reStructuredText output is added to the Sphinx documentation, and since there is a clean separation of content and formatting, it integrates nicely with rest of the documentation.  There are overall stats, author-centric statistics, and activity-centric stats in textual, tabular, and graphic forms. These statistics are regenerated automatically on a nightly basis.

Enjoy ITK Examples!