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
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_. 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
<http://pytest.org/latest/contents.html#>`_ framework.

The preferred way to run the tests is using `tox
<https://testrun.org/tox/latest/index.html>`_, 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
<https://pypi.python.org/pypi/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
:ref:`optdep`. 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.