The Shark Documentation System

Shark uses the well-established Doxygen C++ documentation system in combination with Sphinx, another popular documentation system originating from the Python world. Doxygen is used to extract documentation from the C++ sources, generate inheritance diagrams, etc. To generate the entire surrounding documentation including these tutorials, Sphinx is used.

Building the documentation


To render Latex equations on both Doxygen and Sphinx pages, we rely on MathJax instead of static images locally generated by Latex. MathJax was chosen because vertical alignment of equations rendered by a local latex installation is a pain. To make a user’s browser MathJax-capable, we follow a two-fold approach: first, as a default location for the MathJax.js file, we use an URL to the MathJax content delivery network – that is, all users simply load the default online version of MathJax. However, users with a local installation of the documentation may also want to read the docs when working offline. Thus, both the Doxygen header.html template and the Sphinx layout.html template include a JS snippet that tells the docs to fallback to a local MathJax installation. However, this local MathJax installation is not provided together with Shark and must be inserted by the user to a specific location. MathJax _must_ be located in <SHARK_SRC_DIR>/contrib/mathjax (to be precise, MathJax must be installed such that MathJax.js lives in that folder). The reason we do not distribute MathJax with Shark is that notably the popular Firefox browser does not support the MathJax web fonts (because of a strict same-origin policy even for local sites), thus needs to fallback to image fonts, and these image fonts are 140MB in size. Since we did not want to distribute these along with Shark, any users that want offline equation support for the docs are advised to install MathJax themselves to the abovementioned location.

Maintenance and update issues

Below comes information related to Python, Doxylink, and their updates.

Note for Python3.3 users

Unfortunately, at the time of this writing, docutils does not support Python3.3, see this bug report and patch . Python 3.3 users should thus apply the patch from the link above to their docutils source tree.

For developers

The information below is only relevant for developers who write tutorials and/or wish to alter the appearence of the overall documentation system.

Writing tutorials

See the dedicated tutorial on Writing Shark Tutorials.

Changing the documentation’s appearance

Important files and paths

The general appearance of the Sphinx pages is governed by a “Sphinx theme” and potentially additional CSS stylings and other files needed for styling. Both are located in doc/sphinx_pages/ini_custom_themes. The file theme.conf is the Sphinx theme and derived from the sphinxdoc theme with minor adaptations. The file static/mt_sphinx_deriv.css_t is the stylefile, which still holds some Sphinx directives which will be replaced to create the truly static mt_sphinx_deriv.css for the html pages.

In doc/sphinx_pages/templates you can find the Sphinx/Jinja2 templates which are used to steer the page layout in addition to the theme-based styling.

The folder doc/sphinx_pages/static holds additional images, icons, and sprites needed by the templates.

For doxygen, the header and footer layout is goverened by the files in doc/doxygen_pages/templates, and the CSS styling in doc/doxygen_pages/css.

Assorted hints


  • When linking to boost documentation pages for which you have copied the link from your browser, always replace the current version number (e.g., 1_54_0) in the link with “release”. This will always redirect to the most recent version.

Sphinx and Doxygen html header injection

The Shark homepage injects a css menu header (based on the mollio templates) into the documentation generated by both Sphinx and by Doxygen. If you change the menu layout, remember to change it synchronously in two locations: <SHARK_SRC_DIR>/doc/sphinx_pages/templates/layout.html for all Sphinx pages and <SHARK_SRC_DIR>/doc/doxygen_pages/templates/header.html for all Doxygen pages.

Sphinx and Doxygen connection

Doxygen creates documentation for the classes, namespaces, functions, variables, etc., used in Shark. For the surrounding tutorials (like this page), we use the Sphinx documentation system, which was originally conceived for the Python world. In order to be able to automatically reference pages in the doxygen documentation from within the Sphinx tutorial pages, we use the excellent and highly recommended Sphinx-Doxygen bridge “Doxylink” by Matt Williams. You can find the documentation for Doxylink here and its PyPI package page there .

In <SHARK_SRC_DIR>/doc/sphinx_pages/ the variable doxylink defines additional Sphinx markup roles and links them to a Doxygen tag file. At the moment, the only role is :doxy:, and it links to the global overall tag file for the entire Shark library.