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
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!