.. _developers-docs: 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): .. 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 `__ 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 `. 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: .. doxygenfunction:: make_Vector .. .. doxygenfunction:: make_ParticleContainer_and_Iterators 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: .. code-block:: sh 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 .. code-block:: sh 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.