[Python-Dev] Doctest and Footnotes

[Alexander Belopolsky]

On 7/11/06, Benji York <benji at zope.com> wrote:
[snip]
> I'm not quite sure what you're suggesting.  A guess: put the code that
> isn't to be seen in the __test__ dict with a string key being the name
> of the footnote?

That's right.

>  I don't think a ReST processor would like that much.
> It would see references to footnotes that are never defined.  Or perhaps
> you're suggesting a non-ReST mechanism for the references?
>

I don't know how ReST processor is used.  If you just filter the
output of pydoc through a ReST processor, then you are right about
undefined references. If, however, ReST processing is implemented
inside pydoc, I don't see any problem in implementing __test__ lookup.

> Also, for many of the use-cases we have, we do want the code in the
> test, just not in such a prominent place, and not repeated more than once.

I my use-cases, testing code is clobbering the documentation, but
there is no easy way to move it outside of the docstrings without
breaking the order of evaluation.  I don't use a ReST processor, by I
can read ReST formatted text with little difficulty. I would greatly
appreciate if I could clean the docstrings without loosing the tests.

BTW, another feature that I would greatly appreciate would be a
unittest wrapper which makes each docstring in a separate test case.
Also __new__ and __init__ method docstrings is the natural place to
put set-up code.