Note

This documentation is for a development version. Click here for the latest stable release (v4.0.0).

Contributing to Nengo

Please read our general contributor guide first. The instructions below specifically apply to the nengo project.

Developer installation

If you want to change parts of Nengo, you should do a developer installation, and install all of the optional dependencies.

git clone https://github.com/nengo/nengo.git
cd nengo
pip install -e '.[all]' --user
pre-commit install

If you are in a virtual environment, you can omit the --user flag.

How to run unit tests

Nengo contains a large test suite, which we run with pytest. To run these tests do

pytest --pyargs nengo

Running individual tests

Tests in a specific test file can be run by calling pytest on that file. For example

pytest nengo/tests/test_node.py

will run all the tests in test_node.py.

Individual tests can be run using the -k EXPRESSION argument. Only tests that match the given substring expression are run. For example

pytest nengo/tests/test_node.py -k test_circular

will run any tests with test_circular in the name, in the file test_node.py.

Plotting the results of tests

Many Nengo tests have the built-in ability to plot test results for easier debugging. To enable this feature, pass the --plots to pytest. For example

pytest --plots --pyargs nengo

Plots are placed in nengo.simulator.plots in whatever directory pytest is invoked from. You can also set a different directory:

pytest --plots=path/to/plots --pyargs nengo

Getting help and other options

Information about pytest usage and Nengo-specific options can be found with

pytest --pyargs nengo --help

Writing your own tests

When writing your own tests, please make use of custom Nengo fixtures and markers to integrate well with existing tests. See existing tests for examples, or consult

pytest --pyargs nengo --fixtures

and

pytest --pyargs nengo --markers

How to build the documentation

The documentation is built with Sphinx, which should have been installed as part of the developer installation.

However, one additional requirement for building the Jupyter notebooks that we include in the documentation is Pandoc. If you use a package manager (e.g., Homebrew, apt) you should be able to install Pandoc through your package manager. Otherwise, see this page for instructions.

After you’ve installed all the requirements, run the following command from the root directory of nengo to build the documentation. It will take a few minutes, as all examples are run as part of the documentation building process.

sphinx-build -vW docs docs/_build

Depending on your environment, you might have to set the Jupyter kernel used to build the examples. To set the kernel, use this command.

sphinx-build -vW docs docs/_build -D nbsphinx_kernel_name=<kernelname>

Getting help

If you have any questions about developing Nengo or how you can best climb the learning curve that Nengo and git present, please head to the Nengo forum and we’ll do our best to help you!