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.
cd docs && make doctest
to make the same rst file usable by cram and by sphinx I've done two things.
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.
Made a start on positional.rst
Initial cram doctest setup for positional.rst
Fleshed out positional.rst
Don't use bash highlighting for interactive shell
Add interactive python doctest to positional.rst
Fixed highlighting in positional.rst
Use friendlier names in doc examples
Touchups to positional.rst
Fix indentation in doctest
Add scripts directory to sys.path for doctests
Man, you rock. This is awesome. :)