 |
Peano
|
|
Peano
|
Peano and its toolboxes and extensions follow some very simplistic documentation paradigms:
doxygen;doxygen;.dox.To generate the documentation, cd to your Peano directory, and type:
doxygen documentation/Doxyfile
To understand the following descriptions, it is reasonable to keep the following terminology in mind:
The code on Peano's website is generated everytime we get a top-level push, i.e. a push into the master branch p4. Therefore, the online docu will always lag behind the latest developments. You might be better off with creating your own docu on your branch locally.
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.
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/subdirectory
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.
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:
documentation/Doxygen.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.
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:
\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.
\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:
*/
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,
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.
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.
New chapters are created with the ''' # ''' symbol. This will make "Brief doxygen cheat sheet" in the sidebar, as a drop-down menu within the current page.
# Brief doxygen cheat sheet
You can nest drop-down menus. Add a second sub-level with two hash signs. Note the appearance of "Headings" in the drop-down menu on the left.
## Headings
You can even keep this going. Create a third nested level with three hash symbols ( ''' ### '''' ) and so on.
We use html-style comments.
<!-- Anything in here is ignored by doxygen. -->
If you want code to appear neatly on the page, you have two options.
You can either use tilde (~):
Under the hood:
~~~~~~~~~~~~~~~~~~~~~~~~~ double answer; int counter; ~~~~~~~~~~~~~~~~~~~~~~~~~
You also have the much more powerful "verbatim" keyword:
Inline "code snippets" can be done like so:
```import peano4```
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.
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)
Simply write:
@image html relative/path/to/file.png
You can enumerate lists by starting each new line with
\li
The standard newline character
\n
works as expected. However, it is easiest to create new enumerations or lists via
This section is particularly relevant for tutorials and the documentation of benchmark scripts. Whenever you want to refer to a particular part of a script, a convenient way is to mark this part with
In Python, it is
Please remove the spaces above between the slashes and the exlamation mark. They are in there, as the parser otherwise fails. Once the source code annotation is in, you can refer to this code snippet in the doxygen docu via
This reference will display the code snippet in the generated html code. The outcome resembles what we know from Jupyter notebooks.
1.10.0