Adding Examples, Tests and Documentation

How to Add Examples and Unit Tests

How to add a unit test to the existing setup?

Under the assumption of your test implementation residing in Shark/Test/mytest.cpp, add a line reading SHARK_ADD_TEST( mytest.cpp mytest ) to the file Shark/Test/CMakeLists.txt.

How to add a new example to the existing setup?

Under the assumption of your example implementation residing in Shark/examples/myexamples.cpp, add a line reading SHARK_ADD_EXAMPLE( myexample.cpp myexample ) to the file Shark/examples/CMakeLists.txt.

Using doxygen in Sphinx

To insert a docu to some ENTITY, which could be a classname, function name, group name or file name, just insert :doxy:`Entity` or :doxy:`My link text<Entity>` into the file

Inserting example code in tutorials

To insert example code, we use our own hackish solution using tut2rst. example files are not written as .cpp, but have the ending .tpp. Tutorial files are ending with .tut instead of .rst. Both file formats are automatically converted to their .cpp and .rst counterpart during compilation. Adding a new tutorial or example file requires re-running cmake to update the list of files that are converted.

When you write an example in Shark/examples/folder/my_Example.tpp you can mark sections to be included using:

some code
//###begin<section_name>
code
//###end<section_name>
some more code
//###begin<other_section_name>
code
//###end<other_section_name>

These section markers are removed when the .cpp file is created during build. Section names are allowed to overlap and a section can appear several times. in this case, the section code from different sections is pasted in order in the tutorial. To add the section section_name to your tutorial, use

..sharkcode<folder/my_Example.tpp, section_name>

Configuration of Sphinx

Config of Documentation

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.

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.