We write most of our metagenomic workshops in Sphinx. Simple reStructuredText files (.rst files) are converted into a fancy HTML page. Pretty similar to how this website is generated actually. We thankfully borrowed this concept from Titus Brown’s khmer tutorials. The workshops are usually done on our computing cluster and consist of a series of bash commands that each participant has to write in the terminal. One problem we’ve had with previous workshops is an easy way to test all these commands. Therefore, for our latest metagenomics workshop in Uppsala I wrote a very simple awk script to get just the code blocks from a .rst file:

Code blocks in .rst are started by a double colon, followed by an indented code block and ended by an empty line (could contain whitespaces). Once you get out the code blocks, you can run all the commands by piping it to bash, e.g.

cat index.rst | rst2code - | bash -xe

The -x prints each command before it is run so one can easily detect the line causing an error and the -e halts bash in case an error is found.

I am sure there are better ways to do this using docutils (any tips?), but for a hacky test script for the workshop it worked great.


comments powered by Disqus