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

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

Follow the `Python Syle Guide`_.

Running from source
-------------------
While developing, it is convienent to run the changed code without
uninstalling/installing. Nodeworks can be start in 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 the
documentation can be found in the ``docs/source`` directory.

To build the html documentation, run the following command::

    $ python setup.py build_sphinx

The documentation can also be built by going 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 `nose`_. To install nose use pip::

    $ pip install nose

Tests should located in directories named ``tests`` along side the modules
they are testing. The name of the test files starts with 'test\_' followed by
the module that is being tested.

To run the test harness, run the following command from the command line::

    $ nosetests

or you can run this command::

    $ python setup.py test

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

	$ nosetests test_file.py

To run a specific case in a specific test file::

	$ nosetests test_file.py:TestCase

To run a specific method in a case in a file::

	$ nosetests test_file.py:TestCase.test_method

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

    $ pip install coverage

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

    $ nosetests --with-coverage --cover-package=nodeworks

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

    $ nosetests --with-coverage --cover-package=nodeworks --cover-html-dir=./docs/testcoverage --cover-html

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 conda_recipe

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
.. _nose: https://nose.readthedocs.org/en/latest/
.. _Python Syle Guide: https://www.python.org/dev/peps/pep-0008/
.. _PyPi: https://pypi.python.org/pypi
.. _coverage: http://coverage.readthedocs.org/en/latest/