This documents explains how to setup a virtual environment for developing aiomas, how to build the documentation and how to run its test suite.
You should use at latest version of Python 3 for your devleopment, but at least Python 3.4.
Create a fresh virtualenv with that interpreter and activate it. You can then install all development dependencies with pip:
(aiomas)$ pip install -r requirements-setup.txt
This installs the newest version of everything. If you should into problems with this, you can also install a well-tested set of all dependencies:
(aiomas)$ pip install -r requirements.txt
Apart from installing aiomas in editable mode, it also provides you the following list of tools:
- Flake8: for checking code quality and style guides
- Pytest: for running the tests and measuing the test coverage inside your virtualenv
- Sphinx: for building the documentation
- Tox: for running the test suite with all supported Python versions
- Twine: for uploading packages to PyPI
Building the docs¶
Sphinx is used to build the docs. You can find ReST source files in the
docs/ folder. The output folder for HTML documentation (and other
docs/_build/. The online documentation on Read the
Docs is everytime you push something to Bitbucket.
When once you’ve set-up your venv, you can build aiomas’ documentation this way:
(aiomas)$ cd docs/ (aiomas)$ make html # For quick builds (aiomas)$ make clean html # For a clean/full build
For Windows user, there is a
make.bat which does the same.
You can also let Sphinx check all external links:
(aiomas)$ make linkcheck
You can get a full list of make targets by running
Running the tests¶
You can run all tests by executing:
By default, all doctests in
docs/, all examples
examples/ and all tests in
tests/ are run.
In order to measure the test coverage, run pytest with the following arguments:
(aiomas)$ py.test --cov=src/ --cov-report=html
This will produces a folder
htmlcov with the coverage results.
You can use tox to run the test suite on all supported Python interpreters. It also runs flake8 to do some code quality and style checks. Currently, you need to have python3.4 and python3.5 available in your path. Running tox is then easy:
(aiomas)$ tox [...] ________ summary ________ py34: commands succeeded py35: commands succeeded docs: commands succeeded flake8: commands succeeded congratulations :)
If you cannot / do not want to install all the Python versions, you can limit tox to run only a selected environment:
(aiomas)$ tox -e py35 # Only run tests on Python 3.5 (aiomas)$ tox -e flake8 # Only run flake8 checks