Developer Resources
===================

Style Guide
-----------

Follow the `Python Style Guide`_.

Running from source
-------------------
While developing, it is convenient to run the changed code without
uninstalling/installing. Nodeworks can be run from the top level source
directory by::

  python -m nodeworks

Or, nodeworks can be installed in `develop` mode::

  python setup.py develop

Documentation
-------------
This documentation is created using `sphinx`_. The source files for this
documentation can be found in the ``docs/userguide`` directory.

To build the html documentation, go to the ``docs`` directory and use
the following command::

    $ make html

Basic reStructuredText syntax can be referenced `here`_.

Testing
-------
The test harness is run using `pytest`_. A plugin for testing qt applications,
named ``pytest-qt`` is also required. To install with pip::

    $ pip install pytest pytest-qt

Tests should located in the ``tests`` directory. The name of the test files
starts with 'test\_' followed by the module that is being tested.

To run the test harness, run ``pytest`` from the command line::

  $ pytest

To run a specific test file, use this command::

  $ pytest tests/test_foobar.py

To run a specific test by name::

  $ pytest -k TestCase

`pytest`_ can also measure the code coverage of the tests by using the `coverage`_
plugin. To get the coverage plugin, install it using pip::

  $ pip install pytest-cov

To get a report on the command line, use these flags when running `pytest`_::

  $ pytest --color=yes --no-cov-on-fail --cov=tests --cov-report=term-missing:skip-covered tests

To generate a nice html report showing all the lines that are covered, use the
following flags::

  $ pytest --color=yes --no-cov-on-fail --cov=tests --cov-report=html tests

html files will be created in nodeworks\docs\testcoverage, with index.html being
the entry point.

Qt provides testing tools to mimic user interaction.

.. code-block:: python

   from qtpy import QtGui, QtCore, QtTest

   # click <widget> with left mouse button
   QtTest.QTest.mouseClick(<widget>, QtCore.Qt.LeftButton)

Building conda package
----------------------
First install/update conda build::

    # conda install conda-build

The conda package can be constructed by running the following command in the top
level of the repository::

    $ conda build -c mfix -c anaconda conda_recipe/nodeworks

The package can then be tested by installing with::

    $ conda install --offline path\to\conda-bld\noarch\nodeworks*.tar.bz2

Building whl file
-----------------
Since Nodeworks is pure python, a universal wheel file can be built with the
following command::

    $ python setup.py bdist_wheel --universal

This wheel file can be installed in both python 2 and python 3 installations by
running::

    $ pip install nodeworks.whl

.. _here: http://sphinx-doc.org/rest.html
.. _sphinx: http://sphinx-doc.org
.. _pytest: https://pytest.org
.. _Python Style Guide: https://www.python.org/dev/peps/pep-0008/
.. _PyPi: https://pypi.python.org/pypi
.. _coverage: http://coverage.readthedocs.org/en/latest/