Documenting and Testing sarpy

To make this code usable, it needs to be documented. The easiest and at the same time most helpful way to write documentation are a few examples (copied verbatim from your interactive session) into the docstring. The amazing thing is that this docstring can be parsed by the doctest module in order to automatically run those examples and compare them to the expected output.

We should do more of that!

Inner Workings

The documentation in this package makes use of Sphinx, the automated documentation project. Essentially it harvests the docstrings of all modules and puts it together in a nice and appetizing way. The instruction for this automated compilation of HTML documentation is in the doc folder (Makefile, config.py and some static pre-written, global document pages). Simply going to that directory and issuing make html will recreate the documentation and store it in the html folder. The html folder is bizarrely the working copy of a different, special (orphan) branch named gh-pages. When we push the html pages to github they are processed and will be hosted on (github pages https://DrSAR.github.com/SARlabpy)[https://DrSAR.github.com/SARlabpy]. That domain is also pointed to from our own domain https://code.sarlab.ca.

make html will write a lot of stuff into _build/html. One way to publish this by hand is

• to checkout gh-pages,

• to wipe the entire tree (without getting rid of the .git directory and CNAME),

• to copy the content of html (temporarily stashed somewhere?) into the project root directory, and, finally,

• to (force-?)push to gh-pages upstream.