Marco, thank you for the suggestion of a howto. That is a good idea. 

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

• 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.

• An effective way to write doctests. I suspect that some people write doctests by exercising the functionality in Python's interactive mode, then copy and paste the transcript from that session to the doctests. I don't do it that way, I author in the docstring. Maybe I'm not doing it the best way.

• How to author doctests so that they both prove the module correct, and provide clear and readable documentation. I imagine some effective tests for edge cases and error conditions are important to have, but are not readable documentation. Maybe such tests belong in a unittest framework instead of as doctests.

• How to run doctests from a unittest harness (your earlier note about the unittest API would be a part of this).

A problem for me is that I think I don't have the experience and wisdom to give good advice in these areas. I would be happy to start such a howto, and to accept feedback, and to edit it into good prose. I would need wiser people to contribute good ideas for the howto.

Also, Marco, thank you for being willing to review a patch.  That is helpful.

My next step is to check out the documentation source, to be in a position to make a patch.