Hacking on this Code
--------------------
I'm always open to contributions from others provided that the are not
completely worthless.  I do request that you follow a few basic rules
though.

- (Almost) All code is tested: if you think that your contributions do not
  require tests for whatever reason, please justify it.

- All tests pass.  This is non-negotiable.  If you cannot get a particular
  test case to pass.  Submit the PR on github and we can probably work
  through it.  What I won't do is accept code that breaks a pile of tests
  without any effort to fix them.  Run ``env/bin/detox`` or ``env/bin/tox``
  to run the tests.

- Features are documented.  I use `sphinx`_ for all documentation.  Edit
  the documentation sources as required and make sure that running
  ``python setup.py build_sphinx`` produces something reasonable.

I apologize for being pretty opinionated about this but code quality doesn't
disappear suddenly, it continually degrades.  This set of minimum
requirements is my attempt to help prevent quality issues.


Getting Started
~~~~~~~~~~~~~~~
Congratulations for not being immediately put off by my attitude ;)  Let's
get started.  First thing is to create a new sandbox for you to play in.
If you are using Python 3.4 or newer, use ``pyvenv env`` to create a new
virtual environment in the *env* directory.  Otherwise, install
`virtualenv`_ and run ``virtualenv env`` to create the environment.

**PLEASE DO NOT USE SUDO!  DO NOT INSTALL INTO YOUR SYSTEM ENVIRONMENT!!**

If you did not chuckle at the previous line, then you really do need to pay
careful attention to it.  Use virtual environments for developing code.

Once you have an environment, install the requirements listed in
*dev-requirements.txt*.  This is a pip-formatted requirements file that will
pull in packages that the code depends on as well as packages required to
test, document, and generally hack on the code base.

**TL;DR**

.. code-block:: sh

   $ pyvenv env
   $ env/bin/pip install -r dev-requirements.txt

Running Tests
~~~~~~~~~~~~~
Tests are written using the standard `unittest`_ package and run using
`nose`_ and `tox`_.

.. code-block:: sh

   $ env/bin/tox

Documentation
~~~~~~~~~~~~~
All documentation is written in `ReStructuredText`_ with HTML generated by
the `sphinx`_ utility.

.. code-block:: sh

   $ env/bin/python setup.py build_sphinx

The HTML output is written to *build/sphinx/html*.

.. _nose: http://nose.readthedocs.org
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
.. _sphinx: http://sphinx-doc.org
.. _tox: http://testrun.org/tox
.. _unittest: https://docs.python.org/3/library/unittest.html
.. _virtualenv: https://virtualenv.pypa.io
