[TIP] testing for sysadmins who know bash advice

[Kumar McMillan]

On Jan 8, 2008 1:15 PM, Noah Gift <noah.gift at gmail.com> wrote:
> I am starting to spread the word about Python to many bash
> programmers, both by writing articles, in the book I am writing that
> is geared toward sysadmins, and finally in person one on one.  Any
> suggestions on how to tackle the challenging problem of explaining
> python and teaching that testing is a good thing?  I find this to be
> reasonably complex, as python is foreign enough, but that last thing I
> want to do is turn someone off from Python forever, by getting to
> heavy handed with testing.  I suppose I like explaining doctest best
> so far, as it is so intuitive, and makes sense to a bash programmer.

[catching up on TIP!]

I've actually been toying with the idea of "shelldocs" -- that is,
testable documentation of shell commands.  I mainly wanted this kind
of thing to make sure that some examples I shipped with a module
worked as advertised.  So I wrote up a discovery-based shelldoc thing
that works much like doctest.  However, the examples I have only do
simple shell commands and I haven't thought it through to the point of
making something as versatile as doctest.  If anyone feels inspired by
this, it can easily be extracted into a module and I would be happy to
collaborate on improvements.  Here are the docs with shell commands:

http://code.google.com/p/wikir/

and here is the "meat" :
http://wikir.googlecode.com/svn/trunk/wikir/tests/shelldoc.py
http://wikir.googlecode.com/svn/trunk/wikir/tests/test_shelldoc.py

currently, I am just using a single nosetests generator to validate
all the shell sessions but this could be expanded into some kind of
nose plugin or whatnot.  so far it looks like:

import wikir, inspect, pydoc
from wikir.tests.shelldoc import find_shell_sessions, validate_session

def test_docs():
    doc = pydoc.splitdoc(inspect.getdoc(wikir))[1]
    for session in find_shell_sessions(doc):
        yield validate_session, session


-Kumar