Developers’ Guide

For developers of nuSpaceSim to perform needed improvements, maintenance, and upgrades.

Access Source Code

The version control source repository for nuspacesim is on github.

git clone https://github.com/NuSpaceSim/nuSpaceSim.git
cd nuSpaceSim

Prepare Development Environment

There are a few development tools used by nuspacesim that are not required for users. To fully develop nuspacesim you should install them in your local python environment with

python3 -m pip install -r requirements-dev.txt

These requirements are:

  • black: source code layout formatting

  • flake8: source code health checking

  • pre-commit: enforce requirements before committing

  • pytest: unit test framework

  • tox: python version environment manager and unit test system.

To set up the pre-commit checks you need to install the pre-commit hooks into your git repository, this can be done easily with

pre-commit install

Now every attempt to commit updates to the git repository will run the pre-commit checks, and block any commits that fail.

Development Build & Install

Use the -e flag on pip to build the nuspacesim python wheel as an editable install. This method compiles the code locally and copies a symbolic link to the code into your active python site-packages directory. The consequence of this is that making source code changes to local python files are instantly updated in the installed executable.

python3 -m pip install -e .

Now you are able to execute the nuspacesim command line application as well as import the nuspacesim package in a python interpreter or script.

Build wheel package from source (Optional)

The python wheel is the compiled binary package which is distributed on pypi. You may want to compile the wheel independently of a pip install because you are testing the pypi upload. This is an optional step as it is specifically handled by the CICD github action and does not require developer intervention.

python3 -m pip wheel -w dist --use-feature=in-tree-build --no-deps  .

Build Documentation

The documentation for nuspacesim is compiled from RST files using sphinx. This is a standard best-practice for python packages and open source projects.

Here are links to documentation for the RST syntax and Sphinx. They describe RST features like math directives,

\[ \begin{align}\begin{aligned}α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)\\\ln{x} + C = \int{\frac{1}{x}}\end{aligned}\end{align} \]

Inline math like “The area of a circle is \(A_\text{c} = \left(\frac{\pi d^2}{4}\right)\)”. And code blocks like

if __name__ == "__main__":
    print("Hello World!")

The documentaion dependencies are found in docs/requirements.txt and should be installed in your development environment with

pip install -r docs/requirements.txt

This does not build the docs themselves, only installs the sphinx dependencies.

Build Documentation with tox

The sphinx-build command is fairly complex, so we’ve simplified building the documentation with tox, which will compile the code into a new environment then call the proper sphinx-build command to create the HTML output.

python3 -m tox -e docs

Once this step completes successfully you should be able to open your compiled documentation in any browser by opening the file path stated at the end of the tox output. Something like

firefox file://~/nuSpaceSim/.tox/docs_out/index.html

Run unit tests

The pre-defined unit tests can be run on your system directly with pytest

python3 -m pytest test

Run unit tests on multiple versions of python (Advanced)

First, set up and install pyenv, which will require altering your default shell environment.

Then use pyenv to install multiple versions of python. I specifically use 3.7.11, 3.8.11, 3.9.7, 3.10.0. Then set all of the desired versions as your “local” pyenv python, and check that they’re properly set.

pyenv install 3.7.11 3.8.11 3.9.7 3.10.0
pyenv local 3.7.11 3.8.11 3.9.7 3.10.0
pyenv versions

Finally run the test suite against all versions in parallel with tox.

tox --parallel