Developer Documentation

Development Workflow

  • Fork from github

  • Develop on your fork

  • Test locally

  • Make a pull request

Before making a pull request, make sure that your fork is up to date and that all the tests pass locally. This will make it less likely that your pull request will get rejected by making breaking changes or by failing the test requirements.

Running the tests

The tests require that you have cloned the repository, since the test code is not distributed in the package. It is recommended to use pytest for this. There are two options:

Use the provided Makefile to run the tests using make:

$ git clone https://github.com/BlueBrain/NeuroM.git
$ cd NeuroM
$ make test

This runs pep8, pylint and the unit tests in sequence.

This method takes care of installing all extra dependencies needed for running the tests, diagnosing the results, performing linting on the source code. These dependencies are installed into a virtuanelv named neurom_test_venv:

The Makefile also has targets for running only pylint and pep8 individually:

$ make lint       # runs pep8 and pylint if that succeeds
$ make run_pep8   # run only pep8
$ make run_pylint # run only pylint

Note that you can also install the test dependencies and run the tests inside of your own virtualenv:

(nrm)$ pip install -r requirements_dev.txt

This installs the following packages into your virtualenv unless they are already installed:

mock>=1.3.0
pylint==1.7.4
pycodestyle==2.3.1
pytest>=6.0
pytest-cov==3.7
sphinx>=1.3.0
sphinxcontrib-napoleon>=0.3.0
sphinx_rtd_theme>=0.1.0

Then, run the tests manually in the virtualenv. For example,

(nrm)$ pytest --cov-report term-missing --cov-report xml --cov-report html --cov=neurom neurom

Warning

To ensure that the test requirements are the same as those run in continuous integration, you should run the tests using the make test command. This is the same command used in continuous integration. Failure to pass means will result in a pull request being rejected.

Building documentation locally

To build documentation, go into project’s doc folder.

$ cd doc  # assuming that you start from the project's root.

Make sure you have installed into your virtual environment libraries from requirements_docs.txt in the project’s root. Run the command:

$ make html

This builds the documentation in doc/build. To view it, open doc/build/html/index.html in a browser.

Python compatibility

We test the code against Python 3.6 and 3.7.