BinPro/CONCOCT — pull request #125 by inodb (2014-12-09 16:06:02+00:00)
Title: Add documentation for dnadiff_dist_matrix

This PR adds documentation for the dnadiff_dist_matrix script. This is the first script in the ``scripts`` dir with documentation other than those described in the complete example. Instead of extending the complete example with more and more scripts, it seemed better to have separate documentation for each script. Although we will not officially maintain these scripts it would still be nice to have some place for the documentation. At some points some of these scripts might make it to their own repo, but as of now they seem to fit best within the CONCOCT repo. The idea is that the documentation of each script should show:

- the usage string
- a simple example using test data

For the usage string an extra dependency ``sphinxcontrib-programoutput==0.8`` is added to the documentation requirements that allows one to get the ``--help`` output of a script directly. This has also been updated for the usage documentation of CONCOCT itself. It was quite a hassle to get this to work on RTD, but it works now. The problem is that ``setup.py install`` of CONCOCT does not work because you can't compile C libraries there. I therefore followed an approach similar to [the one in RTD's faq](http://read-the-docs.readthedocs.org/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules). Only problem was that ``programoutput`` does not run the commands in ``conf.py`` before running a python script, so to get the ``--help`` output one should first import/run ``conf.py`` before running the python script itself so that there is a ``Mock`` module loaded instead of the real module. It is still a bit hacky, but it should suffice for now.