Development & Contributing

This section contains information for anyone who wishes to contribute to mpnum. Contributions and pull requests for mpnum are very welcome.

Code style

All contributions should be formated according to the PEP8 standard. Slightly more than 80 characters can sometimes be tolerated if increased line width increases readability.

Unit tests

After any change to mpnum, it should be verified that the test suite runs without any errors. For any new functionality, please provide suitable unit tests. Also, if you find a bug, consider adding a test that detects the bug before fixing it.

A short set of tests takes less than 30 seconds and is invoked with one of

python -m pytest
python setup.py test

Note that the second command also installs the dependencies for tests if they are not present. However, since this command ignores wheel files for the dependencies, it tries to install h5py from source on many systems. This is not trivial and might take some time since it builds the HDF5 binaries from scratch. A better way is to install binaries for the test dependencies via running the following command from the mpnum source code root directory

pip install -r requirements.txt

An intermediate set of tests, which takes about 2 minutes to run, is executed automatically for every commit on GitHub via Travis continuous integration. It can be run locally via

python -m pytest -m "not verylong"
bash tests/travis.sh

A long set of tests takes about 30 minutes and is invoked with

python -m pytest -m 1

Unit tests are implemented using pytest. Every addition to mpnum should be accompanied by corresponding unit tests. Make sure to use the right pytest-mark for each test. The intermediate and long running tests should be marked with the ‘long’ and ‘verylong’ pytest mark, respectively.

Test coverage

Code not covered by unit tests can be detected with pytest-cov. A HTML coverage report can be generated using

python -m pytest --cov-report term --cov-report html --cov=mpnum

Afterwards, the HTML coverage report is available in htmlcov/index.html.

Benchmark tests

In addition to unit tests, there are benchmark tests which measure the runtime of certain functions. To run all benchmark tests, run

python -m pytest -m benchmark

Building the documentation

The HTML documentation uses Sphinx. Building the documentation requires the RTD theme:

conda install sphinx_rtd_theme  # or
pip install sphinx_rtd_theme

On Linux/MacOS, the documentation can be built with a simple

make -C docs html

or

cd docs; make html

After the build, the HTML documentation is available at docs/_build/html/index.html.

sphinx-autobuild can be used to rebuild HTML documentation automatically anytime a source file is changed:

pip install sphinx-autobuild
make -C docs livehtml

On Windows, docs/make.bat may be useful. For more information, see the Sphinx tutorial.