New documentation about opster

[piranha]

This listing sounds good to me, in any case after having at least a bit better structure in place it will be easier to move forward, than it is now.

[oscarbenjamin]

Ok, so how about you create a docs branch and I'll send pull requests to it?

[piranha]

Done. :)

[oscarbenjamin]

I already wrote this on #47 but then I decided it would have been better to discuss it here.

#47 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.