ITK Sphinx Examples Part III: Cross-linking with Doxygen
Introduction
This is the first in a series of articles that describe how Sphinx has been extended to create a powerful example documentation system, the ITK Sphinx Examples.
For previous posts, see
Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, and it has long been a great documentation system for ITK. Some of my favorite pages include the Class Index, which is a good page to use your browser’s find capabilities to locate classes of interest, and the Modules page, which contains a hierarchical view of the toolkit organized by the Groups and Modules of ITKv4.
This article describes how we automatically extract Doxygen to provide immediate, well-formatted class information inline in the ITK Sphinx Examples, create automatic links from Sphinx pages to Doxygen pages, and we indexed the examples stored in the Sphinx repository in Doxygen.
Doxygen to Sphinx
Sphinx is very extensible, and we can use this extensibility to bring Doxygen information into Sphinx. The breathe extension adds a new directive that inserts Doxygen content at a given location but formatted according to the local Sphinx style.
The breathe extension extracts information from the Doxygen generated XML, which can be generated by enabling a simple configuration option. On a side note, links to nightly generated ITK Doxygen HTML, XML, and tag file are available in the footer of all nightly Doxygen pages.
In addition to inserting content, we can also link to Doxygen pages directly with the doxylink directive. This role will expand a given class or method name to the corresponding URL for that item.
For convenience, we combined both the breathe and doxylink extensions into a single directive called breathelink. This directive inserts the documentation for a given class, and it also automatically follows with a link to the full Doxygen documentation.
For the documentation of every example, we include a section at the end called Classes demonstrated. In our documentation, we add
.. breathelink:: itk::TranslationTransform
Sphinx to Doxygen
Example code can also be indexed in Doxygen with the \example Doxygen command. To automate the addition of these examples, the EXAMPLES_PATH Doxygen variable is configured by CMake and the required Doxygen code is generated by CMake.
This results in a listing on the Examples Doxygen tab:
And a listing in the class documentation for all classes that are used in an example:
