Development

Getting Started

If you haven’t already, you’ll want to get familiar with the Toyplot repository at http://github.com/sandialabs/toyplot … there, you’ll find the Toyplot source code, issue tracker, discussions, and wiki.

You’ll need to install ffmpeg and pandoc, neither of which can be installed via pip. If you use Conda (which we strongly recommend), you can install them as follows:

$ conda install ffmpeg pandoc

Next, you’ll need to install all of the extra dependencies needed for Toyplot development:

$ pip install toyplot[all]

Then, you’ll be ready to obtain Toyplot’s source code and install it using “editable mode”. Editable mode is a feature provided by pip that links the Toyplot source code into the install directory instead of copying it … that way you can edit the source code in your git sandbox, and you don’t have to keep re-installing it to test your changes:

$ git clone https://github.com/sandialabs/toyplot.git
$ cd toyplot
$ pip install --editable .

Versioning

Toyplot version numbers follow the Semantic Versioning standard.

Coding Style

The Toyplot source code follows the PEP-8 Style Guide for Python Code.

Running Regression Tests

To run the Toyplot test suite, simply run regression.py from the top-level source directory:

$ cd toyplot
$ python regression.py

The tests will run, providing feedback on successes / failures.

Writing Regression Tests

Many of Toyplot’s tests function by comparing the SVG representation of a toyplot.canvas.Canvas against a reference stored in features/reference. These tests all end with a Behave step along the lines of Then the figure should match the <test-name> reference image, which compares the canvas to the file tests/reference/test-name.svg. The first time to you run a new test that uses this step, it will generate and store the new reference file, then fail, prompting you to examine the reference file to ensure that it’s correct. The next time you run the test, it will function normally, comparing the canvas against the reference file.

If you make changes that cause an existing test to fail, the failed SVG will be written to features/failed/test-name.svg, so you can compare it against the corresponding reference SVG in features/reference/test-name.svg.

Test Coverage

When you run the test suite with regression.py, it also automatically generates code coverage statistics. To see the coverage results, open .cover/index.html in a web browser.

Building the Documentation

To build the documentation, run:

$ cd toyplot/docs
$ make html

Once the documentation is built, you can view it by opening docs/_build/html/index.html in a web browser.