piranha/opster — pull request #47 by oscarbenjamin (2012-06-16 21:46:19+00:00)
Title: Positional section for the new docs

This patch adds a positional arguments section to the docs.

It also adds ```make doctest``` that tests Python snippets with ```cd docs && make doctest``` and tests command line examples with cram.

to make the same rst file usable by cram and by sphinx I've done two things.

1. Add a hidden directive to the ```conf.py``` file use by sphinx. Cram will see the body of the hidden directive but sphinx will ignore it.
2. Use ```--indent=4``` argument to cram. This way cram can be told to ignore a block by setting the indent to something other than 4.

There is a new directory ```docs/scripts``` containing Opster scripts that are shown and used in the docs. The script content is inserted into the docs with ```literalinclude```. The command-line behaviour of these scripts reported in the docs is tested with cram. The behaviour from Python interactive sessions is tested by sphinx/doctest. This means that every aspect of the documentation is automatically tested (when you run ```make doctest```).

Note that the very last doctest is currently failing I'm not sure if that's a bug or if I've misunderstood, but I'll post a separate issue.