Peano 4
Loading...
Searching...
No Matches
Documentation

Peano and its toolboxes and extensions follow some very simplistic documentation paradigms:

  • Everything is in the code;
  • All documentation is created via doxygen;
  • What does not fit into the code is documented in separated files which also are processed by doxygen;
  • Code documentation should be in the header files for C/C++ code;
  • Further documentation files have the extension .dox.

To generate the documentation, cd to your Peano directory, and type: 

  doxygen documentation/Doxyfile

Alternatively, you can also use 

  make doc

Some older versions of doxgen didn't produce the expected documentation for python files (docstrings would be displayed as code blocks rather than doxygen documentation in the html). The current setup is tested with doxygen 1.9.7. This may not be the default version shipped by your OS, but can very easily be installed from https://www.doxygen.nl/download.html .

To understand the following descriptions, it is reasonable to keep the following terminology in mind:

  • A page is the LaTeX equivalent of a chapter.
  • A subpage is the LaTeX equivalent of a section.
  • We typically use the hash signs to substructure information within a section where two hashes denote sections.

Rationale

We aim for documentation which is always up-to-date. The documentation shall be searchable. We want to have one medium which integrates top-level and high-level overview information (normally stored in *.dox files) with low-level source code documentation (normally stored in *.h and *.py files).

Peano's documentation can be quite complex with all the toolboxes and extensions being part of the code plus the fact that we combine C/C++ and Python in numerous ways. Therefore, the file structure of the documentation reflects the logical structure of the menus.

How to add new files

Header files and Python scripts are automatically picked up by the script as long as they are stored within directories which are subject to search. Low-level subpages are automatically generated for them. If you want to write stand-alone docu (such as top-level or high-level overview descriptions), the corresponding dox files should go into 

  documentation/Doxygen/SubDir

Doxygen supports the addition of pages anywhere in the directories that it searches. These can be written in markdown or html. Additionally, files must start with [ /** ] and end with [ */ ], so that Doxygen is alerted to process them.

New (top-level) documentation page

With top-level, we mean something like Peano or ExaHyPE or Swift. Top-level menu entries are reserved for such rubrics and therefore are infrequently introduced. Please consult with the team if you want to add a new top-level entry.

If the team agrees that there should be a new top-level entry, please follow the following conventions:

  • Add a new directory within documentation/Doxygen.
  • Create a new main page within this new directory. Most packages call this file home.dox.

The new mainpage typically reads as follows

/**

         @page peano_home Peano

         \tableofcontents

         \li \subpage action_sets

*/

where peano_home and Peano are to be replaced with the names of your choice.

Next, enumerate all the subpages to be nested within this page below. This prevents these subpages from appearing at the top level menu.

New (high-level) subpages

Subpages are the Doxygen term for something that we would call a section in LaTeX. To create such a section, please follow the following steps:

  • Create a new file within the documentation subdirectory of your choice;
  • Begin the new main page as above (with a \page, page_ref and a page title), i.e. any page to be included should start with
/**

       \page page_ref Page Title

Here, page_ref will serve as a global unique identifier throughout Doxygen. Therefore, we usually use identifiers such as peano_mysection where (in this example) peano is a generic prefix identifying the top-level rubric (page), and mysection is the subpage within the rubric.

  • Any page marked with \page will appear on the top level menu by default. New documentation sections should therefore be added to their corresponding chapter or top-level page (see above) via
           \li \subpage page_ref

where page_ref typically has a structure similar to peano_mysection.

The last item illustrates a fundamental paradigm of Doxygen: All the pages are, in the first lace, one large blob. To introduce parent-child relations, you have to add the child to the parent page. The child page itself does not specify its parent. Through this, you can duplicate entries in the navigation menu: you simply add the subpage to multiple parents.

Don't forget to conclude every dox file with:

*/

Adding (low-level) documentation inside the code

Doxygen recognises comments written following certain rules in C++ and Python source codes. As comments are written differently in these languages, these rules are also different. In C++, a comment section must be wrapped by the first line /** and the last line */ and will contain a (multiline) text between them (describing, for example, a function and its arguments before the function body):

/**
 * Comment title
 *
 * Multiline text
 ...
 * Multiline text
 *
 * ## Subsection 1 for this function or class or namespace
 *
 * More docu in multiline text.
 *
 *
 * ## Subsection 2 for this function or class or namespace
 *
 * More docu in multiline text.
 *
 *
 */

The documentation of a function, class or namespace has to be put before the actual declaration, and it always in the header file in Peano.

In Python, a comment section must be wrapped differently, namely,

"""!
Comment title
This is a Python comment that will make it into the HTML docu
"""

Don't forget the exclamation mark as this allows Doxygen to render a Python comment on a webpage correctly, otherwise the comment text will appear as a code snippet. For Python, the comment has to be put directly after the function or class definition.

Furthermore, if you want to ensure that a full qualfilied name, such as petsc.Project.add_solver() appears in the finished html page, ensure that the .py file that contains the class being referenced sits in the same directory as a __init__.py file, which can be empty. Then all you need to do is reference it like:

petsc.Project.add_solver()

in the .dox file.

Within the individual comments, you can substructure the comments further via the hashtag. Markdown headlines should work, too.

What is a little bit annoying is that Doxygen reads comments within the source code and headers as markdown. Consequently, comments that have an indent greater than five are rendered once again as source code. You have to remove the indentation sometimes. It seems that this mainly affects the Python code, but not the C++ documentation.

Tutorials

We hold tutorials parallel to the actual source code, tests and benchmarks. It is obviously up to the author of a tutorial how to structure the tutorial. However, we found it very useful if tutorials refer to other benchmarks and tests wherever possible rather than duplicating code.

To facilitate this, doxygen allows you to "extract" source code snippets into your documentation pages. The feature is documented at https://www.doxygen.nl/manual/commands.html#cmdsnippet.

The idea is that the code that is relevant/discussed has to be annotated with

//! [tutorials swift2 planet-orbit create project]

Code that you want to display in tutorials, too 

//! [tutorials swift2 planet-orbit create project]

(in C/C++ code) or

#! [tutorials swift2 planet-orbit create project]

Code that you want to display in tutorials, too 

#! [tutorials swift2 planet-orbit create project]

respectively. We can then integrate this code part through

@snippet{lineno} tests/swift2/planet-orbit/planet-orbit.py tutorials swift2 planet-orbit create project

This snippet stems from tests/swift2/planet-orbit/planet-orbit.py.

Doxygen cheat sheet

Creating new chapters within the page (note what appears in the dropdown on the left hand side) is done with the "=" symbol. The above chapter above is written under the hood as:

Brief doxygen cheat sheet
======================

Comments

We use html-style comments.

<!--

Anything in here is ignored by doxygen.

-->

Headings

Bold headings such as the one above are created with two hash symbols. This creates a "secondary" chapter. The above line, under the hood, reads:

## Headings

Code snippets

If you want code to appear neatly on the page, you have two options.

You can either use tilde (~):

double answer;
int counter;

Under the hood:

~~~~~~~~~~~~~~~~~~~~~~~~~
double answer;
int    counter;
~~~~~~~~~~~~~~~~~~~~~~~~~

You also have the much more powerful "verbatim" keyword:

\verbatim
Anything in here is rendered exactly as written. Keywords and all.
\endverbatim

Inline "code snippets" can be done like so:

```import peano4```

TeX

Inline math environments can be done as normal. If we want to write \( \int_a^b f(x) dx \), then we must write:

@f$ \int_a^b f(x) dx @f$

Note the change $ -> @f$

You can also render a lot more fancy equations as well. This is the expected output, if you have a proper build of Latex on your system:

\begin{eqnarray*} g &=& \frac{Gm_2}{r^2} \\ &=& \frac{(6.673 \times 10^{-11}\,\mbox{m}^3\,\mbox{kg}^{-1}\, \mbox{s}^{-2})(5.9736 \times 10^{24}\,\mbox{kg})}{(6371.01\,\mbox{km})^2} \\ &=& 9.82066032\,\mbox{m/s}^2 \end{eqnarray*}

The pattern is something like:

\f{eqnarray*}{
    Anything between these braces is rendered in the math environment. 
    Make sure to end your lines with \\
\f}

You can read further on the Doxygen website here.

Including hyperlinks

Recall that a page typically begins with

...
@page page_ref Page Title
...

You can then reference this page from any other. Just state:

... for further reference please see \ref page_ref ...

We can do the same for weblinks, like this one to the gitlab:

[this one to the gitlab](https://gitlab.lrz.de/hpcsoftware/Peano)

Including images

Simply write:

@image html relative/path/to/file.png

Misc

You can enumerate lists by starting each new line with 

\li

The standard newline character 

\n

works as expected.