This guide will show you how to set up a development environment for mosaik or components of its ecosystem (like the Python API), how to run the tests, check the code coverage and quality, and build the documentation.
Change to the directory where you keep your code and clone the mosaik-repository. Create a virtualenv with a Python 3 interpreter and install all development dependencies. Finally, install mosaik in editable mode:
$ cd ~/Code
$ hg clone ssh://hg@bitbucket.org/mosaik/mosaik
$ cd mosaik
$ mkvirtualenv -p /usr/bin/python3 mosaik
(mosaik)$ pip install -r requirements.txt
(mosaik)$ pip install -e . # Install mosaik in "editable"
An “editable” installation just means, that changes you introduce in the repository are automatically reflected in you installation (and thus in your tests).
To run all tests, simply execute py.test:
$ py.test
It will automatically run all code examples in the docs/ as well as the actual tests from mosaik/test/. Pytest’s behavior can be controlled via the [pytest] section in the setup.cfg file and via command line arguments (see its documentation or py.test –help).
You should also regularly check the code/branch coverage:
$ py.test --cov=mosaik
You can also generate HTML files from your source that highlight uncovered lines:
$ py.test --cov=mosaik --cov-report=html
$ [kde-]open htmlcov/index.html
Take a look at the docs of pytest-cov for more help.
Before making a release (and in between) you should make sure that the tests are passing on all supported Python versions. You do this with tox. Tox’ config file tox.ini will show you which versions we support. Every interpreter listed here (e.g., Python 3.3 or PyPy) should be installed on your system. Running tox is than very easy:
$ tox
...
_______ summary ________
py33: commands succeeded
py34: commands succeeded
congratulations :)
Mosaik follows – as most Python projects – relatively strict coding standards.
You should regularly run flake8 to perform PEP8 style checks and and run some analyses to find things like unused imports:
$ flake8 mosaik
It takes its configuration from setup.cfg.
We use Sphinx to create mosaik’s documentation:
$ cd docs/
$ make html
This will build the documentation to docs/_build/html.
When you push new revisions to mosaik’s main repo (bitbucket.org/mosaik/mosaik) the official documentation is automatically updated via a hook.