Before pull request

If it isn’t tested, it’s broken

Unit tests are crucial part of this library. Before submitting a pull request, make sure that all new functions and classes come with tests that completely cover new features. We use tools provided by the pytest package to verify that all statements perform as expected.

First, you will need to install some additional software:

pip install -e '.[tests]'

To run test, simply execute inside the directory(ies) with your changes:

pytest -v --cov . --cov-branch --cov-report term-missing

Here is a youtube video that could help you if you have never been dealing with this side of software development.

Document your code

Documentation is a crucial part of this library. All functions and classes should come with useful docstrings. For these, we use the numpy style docstrings. Detailed guidelines can be found here1 and here2. Also you can have a look at the examples. Can be useful to read introduction to structuring documentation of your module using Sphinx.

It is advised to check you documentation after you have edited the source code. You can edit the documentation using any text editor and then generate the HTML output by typing make html from the docs/ directory

cd docs

# Clean autogenerated files
make clean

# Build html
make html

Open docs/build/html/index.html in a web-browser in order to see the generated HTML output

Note

Building the documentation requires additional packages, e.g. sphinx, numpydoc, guzzle_sphinx_theme and m2r, so you can use extra option during installation

pip install -e '.[docs]'

Docker validation (optional)

Optionally, you can use Docker and corresponding utilities from the Makefile, in order to ensure that there are no local dependecies. Specificaitons for the Docker image can be found in corresponding under docker/ directory

# Create docker image with installation of local state of 'hottbox'
make dev-image  # Size 850MB; built on top of conda/miniconda3

# Start docker container of the image from previous step
make dev-container

# Inside docker container; Should finish without errors
make test-cov     # performs unit tests with coverage
make html         # builds documentation

Note