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:
- http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html
- http://sphinx.pocoo.org/rest.html
- http://matplotlib.sourceforge.net/sampledoc/
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