Contribute to VDAT

Coding style

All the code should be compliant with the PEP 8.

The code should also be thoroughly documented. We follow the numpy style. See the existing documentation.

Testing

Every part of the code should be tested and should run at least under python >=2.7 and >=3.4

The tests are written using the pytest framework.

The preferred way to run the tests is using tox, an automatised test help package. If you have installed tox, with e.g. pip install tox, you can run it typing:

tox

It will take care of creating virtual environments for every supported version of python, if it exists on the system, install vdat, its dependences and the packages necessary to run the tests and runs py.test

We also provide a setuptools command to run tox. If you run:

python setup.py tox

all the needed dependences, among others tox itself, will be fetched and installed in a .eggs directory. Then it will run tox. This command might fail when running in a virtual environment. If you get ImportError: No module named 'numpy' while installing scipy, install numpy by hand pip install [--user] numpy and rerun it again.

You can run the tests for a specific python version using:

py.test

or:

python setup.py test

You can run specific tests providing the file name(s) and, optionally the name of a test. E.g.:

py.test tests/test_flat.py  # runs only the tests in the flat file
py.test tests/test_flat.py::TestFlat  # runs only the tests in the TestFlat class

Relevant command line options:

-v                    verbose output: print the names and parameters of the
                      tests
-s                    capture standard output: can cause weird interactions
                      with the logging module
--noremove            Do not remove output created output files when
                      tearing down the tests. Useful to inspect the log
                      files created by vhc when updating the tests
--singleproc          Run tests only in single processor mode; useful for
                      debugging

A code coverage report is also created thanks to the pytest-cov plugin and can be visualized opening into a browser cover/index.html. If you want a recap of the coverage directly in the terminal you can provide one of the following options when running py.test:

--cov-report term
--cov-report term-missing

For other command line arguments type:

py.test -h

For a list of available fixtures type:

py.test --fixtures tests/

Documentation

To build the documentation you need the additional dependences described in Optional dependences. They can be installed by hand or during vhc installation executing one of the following commands on a local copy:

pip install /path/to/vhc[doc]
pip install /path/to/vhc[livedoc]

The first install sphinx, the alabaster theme and the numpydoc extension; the second also sphinx-autobuild.

To build the documentation in html format go to the doc directory and run:

make html

The output is saved in doc/build/html. For the full list of available targets.

If you are updating the documentation and want avoid the edit-compile-browser refresh cycle, and you have installed sphinx-autobuild, type:

make livehtml

then visit http://127.0.0.1:8000. The html documentation is automatically rebuilt after every change of the source and the browser reloaded.