Developer Guide

This developer guide provides information for developers who wish to modify kafe2. It currently only covers tools needed for development. A description of the software design will be added at some point in the future.

Tools

This section covers software dependencies needed for development and how to use them. All command line instructions below assume that the current working directory is the root of the kafe2 repository.

Requirements

The following software should be installed on your machine:

• git

• Python, both Python 2 and Python 3

• ROOT

Additionally, the following Python packages should be installed:

• NumPy

• Scipy

• iminuit <2

• matplotlib

• numdifftools

• PyYaml

• six

• funcsigs

• tabulate

• unittest2

• coverage

• Sphinx

• Sphinx Bootstrap Theme

• mock

For support of newer versions of iminuit check out the current GitHub issue.

To install all of these packages automatically run:

pip2 install -r dev_dependencies.txt
pip3 install -r dev_dependencies.txt

Running Unit Tests

To run unit tests for both Python 2 and Python 3 run:

python2 -m unittest discover -v -s kafe2/test
python3 -m unittest discover -v -s kafe2/test

Determining Test Coverage

To determine the test coverage run:

coverage run

This will run Python3 unit tests and keep track of the lines that were executed. To print out a general report of the coverage run:

coverage report

To get the lines of a specific file that were not tested run:

coverage report -m path/to/file

For a graphical representation of the result an HTML document can be created:

coverage html

Building the Documentation

To build the documentation run:

cd doc
make

For creating only the html or pdf documentation run make html or make latex. Cleaning the output directories can be done with make clean.

Coding Style

In general the code of kafe2 tries to follow the guidelines of PEP-8. We’ve decided to use a maximum line length of 100 characters for all files.

But please, do not try to enforce this only for the sake of updating the style. Only update the coding style if you’re already performing other changes on a particular section. There might be some sections in the source code which do not follow the general style guidelines, this is okay, as long as the code is working and understandable.

Docstrings

Documenting every method is a very good idea in general, so that a user or developer can quickly and easily understand what a specific code block does and what it is used for. Sphinx is used for creating the documentation, hence we use the Sphinx docstring format.

Since we also support Python 2, we can’t use Python’s own type hints introduced with Python 3.5. Modern IDEs can also perform type checking with the help of docstrings. That’s why, in general, we try to include the types inside the docstrings.