Documentation

Python API documentation

Note

TODO: document the Python doc style we use.

We add docstrings for pybind11-created types and functions. In order to retrieve those, one usually would need to build pyAMReX and have it available (installed) as a working Python import. This build step can be complicated for building documentation and it does not work well with autocompletion in IPython.

Thus, on every merge to the mainline development branch, we build pyAMReX and create “stub” (interface/facade) files that carry all type information and doc strings. We do this by building pyAMReX and running the script .github/update_stub.sh, which uses pybind11-stubgen to extract these information. A GitHub action then commits the updated stub files (.pyi) to the repository.

When we build our Sphinx documentation, we copy the .pyi files and generate documentation of classes and functions via autodoc. The logic for this resides in docs/source/conf.py. We also provide a zip archive online under https://pyamrex.readthedocs.io/en/latest/_static/pyapi/amrex.zip that can be downloaded by dependent projects that build their Sphinx docs.

Doxygen documentation (C++)

pyAMReX uses a Doxygen documentation for its C++ part. Whenever you create a new class, please document it where it is declared (typically in the header file):

/** 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 for more information. Similarly, please document functions when you declare them (typically in a header file) like:

/** 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 linked here.

Breathe documentation

Your Doxygen documentation is not only useful for people looking into the C++ side of the pyAMReX code, it is also part of the pyAMReX online documentation based on Sphinx! This is done using the Python module Breathe, that allows you to read Doxygen C++ 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 make_Vector in src/Base/Vector.H and include it to the html page generated by Sphinx:

template<class T, class Allocator = std::allocator<T>>
void make_Vector(py::module &m, std::string typestr)

Register an amrex::Vector type with pybind11.

Specialized for a specific data type T and memory Allocator.

Template Parameters:

  • T – data type per vector element

  • Allocator – the memory allocator, e.g., an AMReX Arena or std::allocator

Parameters:

  • m – the pyAMReX pybind11 module object

  • typestr – a unique suffix for the type T and Allocator

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, change into docs/ and install the Python requirements:

cd docs/
pip install -r requirements.txt

You will also need Doxygen (macOS: brew install doxygen; Ubuntu: sudo apt install doxygen).

Then, to compile the documentation, use

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.