> In parallel, I was thinking of some howto content that I would like to
> see documented.

Great :-)

> How to decide what to test with doctests and what with unittests.
> I have a feeling that the sweet spot of doctests is functionality
> which you can invoke in one line, and which produces one line of
> output which you can match against a reference string. If it takes
> many lines to set up, or invoke, or checking for correctness is
> more than a test for string equality, then maybe unittest is a
> better tool.

All your questions come up every time I speak about doctest, and these doubts are the main reason for my previous sentence: "there is more to say [about doctest] than only the API". That is why IMO an howto could be really helpful. What doctest checks is not one line of output, but the output as a string, and of course it could have multiple lines. Try to execute the doctest (with the -v option) for this docstring:

def foo():
    """ 
    >>> a = 33
    >>> a
    33
    >>> for i in range(2):
    ...   print(i)
    ...
    0
    1
    """

Three tests will be executed: one for `a=33`, expecting nothing, one for `a`, expecting 33 as output, and one test for the whole `for` block, expecting one output composed of two lines.

For several reasons IMO doctest is not a substitute for unittest. They are different tools for different purposes, as thier name point up. To have a wide view, usually it is a good idea to start from the beginning:

https://groups.google.com/forum/#!msg/comp.lang.python/DfzH5Nrt05E/Yyd3s7fPVxwJ

Anyway, IMO this is not the right place to discuss and explain the objectives of doctest. I propose you to open a repository on github, work and discuss there, and when all is ready, we can ask for a review. Please write here the link to the github repo, so anyone else wants to contribute can find it. Thanks again for your time