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.