Documentation

Documentation Overview

Where can I find the documentation?

The documentation is hostet at https://nu-radio.github.io/NuRadioReco/.

How should I document my code?

All parts of the software are documented in the source code using python docstrings. Human-Readable documentation can then be generated using Sphinx. We use the numpy docstring syntax (https://numpydoc.readthedocs.io/en/latest/format.html).

I just wrote some code, what do I need to do to update the Documentation?

If you added, changed or removed a function in an existing module, there is nothing else you need to do (just make sure all your functions have docstrings). The same is true for changing or adding docstrings, your changes will automatically be included the next time the documentation is generated.

If you added a new module, you need to make sure sphinx knows about it. To do so, go into the autodoc folder and open the .rst file corresponding to the folder that your module is in. The file contains a list of modules inside the folder that should be included in the documentation, so just add your module to the list and the next time the documentation is generated it will be included.

We update the documentation regularly (about weekly), but if you don't want to wait that long, here is how to update it yourself:
First you need to set up a repository for the gh-pages branch. Just follow the steps in the section Setting up cloned repos on another machine from this tutorial: https://daler.github.io/sphinxdoc-test/includeme.html
The directory in which to set up the gh-pages repo (called sphinxdoc-test-docs in the tutorial) is specified under BUILDDIR in NuRadioReco/autodoc/Makefile . In our case, it is a folder called docs_NuRadioReco next to your NuRadioReco repo.
Once you set everything up, go into the NuRadioReco/autodoc directory and do make html. This generates the documentation into the docs_NuRadioReco directory. Go into that directory and commit all changes to the html files. Push them to github and the documentation is updated.

How does the documentation actually work?

To generate the documentation from scratch, sphinx-apidoc https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html is used.

The documentation uses the sphinx rtd theme, which has to be installed before generating the documentation html files (pip install sphinx-rtd-theme). Some custom css code is stored under custom_scripts/styling.css .

The generated html documentation has to be pushed onto the gh-pages branch in order to be hosted on github. To set this up, follow this tutorial: https://daler.github.io/sphinxdoc-test/includeme.html

How to version the software

There is a separate version for the software and the file format. The version of the software is defined at top level init.py (standard for python projects):

• the version is 1.0 in increments of .1 for everything that changes physics behavior (no documentation changes, no cosmetics, etc.)
• a tag on git should be added for every increment

The file version is defined in NuRadioRecoio.py

• There are major versions that break backwards compatibility and minor increments for paramter changes.

Every time old files are still readable with a new NuRadioReco version. Then file version remains constant but the NuRadioReco version goes up. However, if the file version is changed, one should also make a new NuRadioReco version.