Developer Guide

Development environment

Use tox to prepare virtual environments for development.

To set up a Python 2.7 environment in .devenv27, run:

$ tox -e devenv27

To set up a Python 3.4 environment in .devenv34, run:

$ tox -e devenv34

Add requirements for the development environments to the requirements-dev.txt file.


This package uses setuptools.


$ python sdist


$ python bdist


$ python bdist_wheel

to build a source, binary or wheel distribution.

Complete Git Integration

The package is maintained in a git repository. The setuptools script uses the information of tags to infer the version of your project with the help of setuptools_scm. To use this feature you need to tag with the format MAJOR.MINOR[.PATCH] , e.g. 0.0.1 or 0.1.


$ python --version

to retrieve the current PEP440-compliant version. This version will be used when building a package and is also accessible through percolate.__version__.

Unleash the power of Git by using its pre-commit hooks. Make sure pre-commit is installed, e.g. pip install pre-commit, then just run pre-commit install.

Sphinx Documentation

This project follows the NumPy documentation style.

Build the documentation with:

$ tox -e docs

Add further options separated from tox options by a double dash --:

$ tox -e docs -- --help

Add requirements for building the documentation to the requirements-doc.txt file.

Continuous documentation building

For continuously building the documentation during development, run:

$ tox -e cdocs

Unittest & Coverage


$ tox -e py27


$ tox -e py34

to run all unittests defined in the subfolder test with the help of tox and py.test.

The py.test plugin pytest-cov is used to automatically generate a coverage report.

Continuous testing

For continuous testing in a Python 2.7 environment, run:

$ tox -e c27

For continuous testing in a Python 3.4 environment, run:

$ tox -e c34

Requirements Management

Add requirements to the requirements.txt file which will be automatically used by


A CiteULike group manages the bibliography.

To download the bibliography, run

$ doit download_bib

Continuous Integration

pypercolate uses Travis to run the tests on each commit. Travis also reports the test coverage to Coveralls. If further deploys each tagged commit as a release to the Python Package Index (PyPI). continuously measures “Code Health”.

ReadTheDocs builds and hosts this documentation.