.. _developers-docs:

Documentation
=============

.. warning::

   Needs info on how to install all pieces to compile the doc! Some basic info is in the ``CONTRIBUTING.md`` .

Doxygen documentation
---------------------

WarpX uses a Doxygen documentation. Whenever you create a new class, please document it where it is declared (typically in the header file):

.. code-block:: cpp

   /**
    * 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

  /**
   * 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.
   */
  void my_class::my_function(int* my_int);

A HTML rendered version of the Doxygen documentation `is located here <../_static/doxyhtml/index.html>`_.

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/en/master/>`__! This is done using the Python module `Breathe <http://breathe.readthedocs.org>`__, that allows you to read Doxygen documentation dorectly in the source and include 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:

  .. doxygenclass:: WarpXParticleContainer

Exhale documentation
--------------------

Very similar to Breathe, the Python module `exhale <https://exhale.readthedocs.io/en/latest/>`__ reads the full Doxygen documentation and renders it in ` rst <https://en.wikipedia.org/wiki/ReStructuredText>`__ format, and is accessible from the main WarpX ReadTheDocs page.