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!


3 Responses to ITK Sphinx Examples Part I: Credits via GitStats

  1. Andrew Maclean says:

    This is great!

    I like Sphinx because of the reStructured text, but I have only used for for Python documentation.

    The ITK examples are really nicely presented. Is the whole process automated or is there still a lot of manual processing involved in documenting the examples?

    I also like the links to the Doxygen Documentation.

  2. Matt McCormick says:

    Hi Andrew,

    Yes, the whole process is completely automated, and any regressions or issues are reported to the Insight Toolkit software quality dashboard [1] on a nightly basis.

    Sphinx in great for many languages, including the upcoming CMake 3.0 release! [2]

    Stayed turned for an explanation on how two-way Sphinx-Doxygen cross referencing and content extraction works!




  3. Mike Delarus says:

    I’ve looked at sphinx and for documentation (as in writing, images, markup) it is extremely limited.
    What a disappointment.

    Sphinx suffers from:

    * limited markup (no text color, no bold and at the same time italic text, very limited tables)
    * bad pdf output (using table with cells that span rows/cols the pdf output is broken; no good image placement)

    The only use for Sphinx is if you use its autodoc feature; but certainly not as a decent documentation system (for writing)… because that it is not.

    But I can recommend asciidoc (esp. in combination with the asciidoctor tool).

    Asciidoc(tor) has

    * extensive markup (colors, flexible tables, good image placement)
    * good pdf output (via asciidoctor-fopub)
    * Books have been written with it (the new 2nd edition of Pro Git is written using asciidoctor : )
    * Linus Torvalds likes it as well — google it 😉

Questions or comments are always welcome!