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

.. code-block:: none

	..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 <http://www.mollio.org>`_) 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.

