How to Work on CMPy

Writing Documentation

This document will describe a typical workflow for a developer working on CMPy. The first thing we all must do is have a copy of CMPy checked out from the main repository:

git clone git@vcs.cse.ucdavis.edu:cmpy.git

If this command does not work, you probably don’t have your public key on file with the CSE. In this case, please send an email to help@cse.ucdavis.edu and request an account.

CMPy is developed using the git distributed version control system. If you’re familiar with it already: fantastic, dive right in! If not, here is a good introduction to git and its workings.

Once you have a working copy of CMPy it’s time to create a branch to do our work on:

git checkout -b rj_block_entropy_tutorial

This creates a branch named rj_block_entropy_tutorial for us to work on so that our changes can be kept separate until they’re ready to be merged in to the main line of development.

With that out of the way, we can get down to the task at hand: writing a tutorial! Fire up your favorite text editor and create a new file in cmpy/docs/source/tutorials/ called block_entropy.rst. This will be our tutorial’s home. Before we actually begin to work on it, we should make sure it can be found and included in the documentation website. To do this we edit cmpy/docs/source/tutorials/index.rst and add block_entropy to the table of contents:

.. toctree::
   :maxdepth: 2

   onset_of_chaos
   block_entropy

Next we actually write the tutorial. There are many resources available online to help with this task:

Once you’ve finished a chunk of work, you should commit it so it doesn’t get lost:

git add index.rst
git add block_entropy.rst
git commit

You’ll be asked to supply a message. Try something like “added a new tutorial on plotting a machine’s block entropies”.

When you’ve finished writing your tutorial its time to merge it back in to the master development line:

git checkout master
git merge rj_block_entropy_tutorial

And once it’s been merged, it can be pushed back up to the server so that everyone else can enjoy the fruits of your labor:

git push

You can also build the documentation yourself to see how wonderful your new tutorial has turned out:

cd cmpy/docs
sphinx-build source html

This will build all the documentation and place the html files in cmpy/docs/html, which you can then open in your web browser.

Writing Code

When working on code, the procedure is much the same as when writing documentation. The major difference is that the changes you make to the code may have far-reaching concequences. To attempt to minizize any such problems from ocurring there are some standard tools to employ. The first and by far most important of these is unit tests. As an example, here is a unit test for the infotheory module:

def test_mutual_information_zero():
    """
    Ensure that independent events share no information.
    """
    dist0 = create_iid_words()
    assert_almost_equal(dist0.mutual_information([0], [1]), 0)
    assert_almost_equal(dist0.mutual_information([0], [2]), 0)
    assert_almost_equal(dist0.mutual_information([1], [2]), 0)
    assert_almost_equal(dist0.mutual_information([0], [1, 2]), 0)
    assert_almost_equal(dist0.mutual_information([1], [0, 2]), 0)
    assert_almost_equal(dist0.mutual_information([2], [0, 1]), 0)
    assert_almost_equal(dist0.mutual_information([0], [1], [2]), 0)

Here we create a distribution of IID random variables and check that all the mutual informations therein are zero, as they should be if all the variables are independent. You should always write unit tests for any new code you add to CMPy. It also serves the aditional purpose of showing someone how to use the code. To verify that the changes you’ve made to the code haven’t adversely affected anything, we run the tests:

nosetests
............................................................................
............................................................................
............................................................................
.......................................................S.....S...S.S......S.
...............................
----------------------------------------------------------------------
Ran 335 tests in 57.015s

OK (SKIP=5)

You can also check your code for bugs using pylint or pyflakes:

pylint code.py
pyflakes code.py

If you’ve added a new file to CMPy, you’ll also have to run a script to get its documentation added to the API reference:

cd cmpy/docs/
./generate_modules.py -d source/modules -s rst ../cmpy