Documentation and tests

Documentation is handled by sphinx and readthedocs.

Testing is a joint effort between nosetests, travis-ci, and coveralls.

Documentation

Sphinx reads files in reStructuredText and builds a set of HTML pages. Every time a new commit is pushed to github, readthedocs automatically updates documentation.

Additionally, sphinx knows all about python! The directives automodule, autoclass, autofunction and more instruct sphinx to inspect the code located in paradrop/daemon/paradrop/ and build documentation from the docstrings within.

For example, the directive .. automodule:: paradrop.backend will build all the documentation for the given package. See Docstring Conventions for details.

All docstring documentation is rebuilt on every commit (unless there’s a bug in the code.) Sphinx does not, however, know about structural changes in code! To alert sphinx of these changes, use the autodoc feature:

sphinx-apidoc -f -o docs/paradrop paradrop/daemon/paradrop/

This scans packages in the paradrop/daemon/paradrop directory and creates .rst files in docs/paradrop.

To create the documentation locally, run:

cd docs
make html
python -m SimpleHTTPServer 9999

Open your web browser of choice and point it to http://localhost:9999/_build/html/index.html.

Testing

As mentioned above, all testing is automatically run by travis-ci, a continuous integration service.

To manually run tests, install nosetest:

pip install nose

Install the required packages:

pip install -r docs/requirements.txt

Run all tests:

nosetests

How does nose detect tests? All tests live in the tests/ directory. Nose adheres to a simple principle: anything marked with test in its name is most likely a test. When writing tests, make sure all functions begin with test.

Coverage analysis detects how much of the code is used by a test suite. If the result of the coverage is less than 100%, someone slacked. Install coveralls:

pip install coveralls

Run tests with coverage analysis:

nosetests --with-coverage --cover-package=paradrop