1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
.. _developers-docs:
Documentation
=============
Doxygen documentation
---------------------
WarpX uses a `Doxygen documentation <https://www.doxygen.nl/manual/docblocks.html>`__.
Whenever you create a new class, please document it where it is declared (typically in the header file):
.. code-block:: cpp
/** A brief title
*
* few-line description explaining the purpose of my_class.
*
* If you are kind enough, also quickly explain how things in my_class work.
* (typically a few more lines)
*/
class my_class
{ ... }
Doxygen reads this docstring, so please be accurate with the syntax! See `Doxygen manual <http://www.doxygen.nl/manual/docblocks.html>`__ for more information. Similarly, please document functions when you declare them (typically in a header file) like:
.. code-block:: cpp
/** A brief title
*
* few-line description explaining the purpose of my_function.
*
* \param[in,out] my_int a pointer to an integer variable on which
* my_function will operate.
* \return what is the meaning and value range of the returned value
*/
int my_class::my_function(int* my_int);
An online version of this documentation is :ref:`linked here <development-doxygen>`.
Breathe documentation
---------------------
Your Doxygen documentation is not only useful for people looking into the code, it is also part of the `WarpX online documentation <https://ecp-warpx.github.io>`_ based on `Sphinx <http://www.sphinx-doc.org>`_!
This is done using the Python module `Breathe <http://breathe.readthedocs.org>`_, that allows you to write Doxygen documentation directly in the source and have it included it in your Sphinx documentation, by calling Breathe functions.
For instance, the following line will get the Doxygen documentation for ``WarpXParticleContainer`` in ``Source/Particles/WarpXParticleContainer.H`` and include it to the html page generated by Sphinx:
.. code-block:: rst
.. doxygenclass:: WarpXParticleContainer
Building the documentation
--------------------------
To build the documentation on your local computer, you will need to install Doxygen as well as the Python module `breathe`.
First, make sure you are in the root directory of WarpX's source and install the Python requirements:
.. code-block:: sh
python3 -m pip install -r Docs/requirements.txt
You will also need Doxygen (macOS: ``brew install doxygen``; Ubuntu: ``sudo apt install doxygen``).
Then, to compile the documentation, use
.. code-block:: sh
cd Docs/
make html
# This will first compile the Doxygen documentation (execute doxygen)
# and then build html pages from rst files using sphinx and breathe.
Open the created ``build/html/index.html`` file with your favorite browser.
Rebuild and refresh as needed.
|
