This is a technical guide for people already familiar with scientific Python software development. For an introduction to scientific Python software development, see Become a contributor.

Development guide

Testing

Atomap has a large number of unit tests, which are tested using pytest:

$ python3 -m pytest --doctest-modules atomap/

This also runs every docstring example as a unit test.

The documentation is tested by doing:

$ python3 -m pytest --doctest-glob="*.rst" doc/

Both the unit tests and the doc tests can be accelerated by running the tests in parallel. Use the xdist pytest package for this. To run the tests using 5 parallel processes:

$ python3 -m pytest -n 5 --doctest-modules atomap/
$ python3 -m pytest -n 5 --doctest-glob="*.rst" doc/

Testing notebooks

The Jupyter notebooks in https://gitlab.com/atomap/atomap_demos is also tested using pytest and nbval.

$ python3 -m pytest --nbval-lax introduction_to_atomap.ipynb

Note: for some reason the %matplotlib widget or %matplotlib qt causes the tests to fail, the easiest way of avoiding this is skipping that specific notebook cell. This done by adding nbval-skip to the tag for that cell.

Style checks

In Atomap the PEP8 style guide is followed, and the Black code formatter is used. To automatically format the code:

$ python3 -m black atomap/

To only check the code, without changing it:

$ python3 -m black atomap/ --diff --check

Generating the sphinx page

These documentation pages are written by using sphinx. You generate the html site by:

$ cd doc
$ python3 -m sphinx -b html ./ _build/html/

Continuous integration

The Continuous integration (CI) settings is contained in .gitlab-ci.yml. This runs all the above-mentioned tests, style checks and sphinx page generation on each branch.

Documentation from development branch

The most recent documentation generated from the development branch can be accessed here.