[Python-Dev] Doctest and Footnotes

[Phillip J. Eby]

At 11:36 PM 7/10/2006 -0400, Benji York wrote:
>The footnote code is executed every time the footnote is referenced, and
>is /not/ executed at any other time (i.e. it's not executed at the point
>the footnote is defined).  A warning is generated if a footnote (that
>includes code) is defined but never used.
>
>This would allow moving repetitive or verbose code (e.g. tests for
>corner cases) into footnotes so they won't hinder the documentation
>aspect of a test.  It also allows defining reusable bits of setup code,
>freeing the doctest author to structure the prose as they wish instead
>of being constrained by having to place bits of code with common
>environmental needs together.
>
>I've implemented this in a branch of zope.testing (which contains a copy
>of a post-Python 2.4.3 version of doctest (http://tinyurl.com/nekam).
>The behavior is controlled by an optionflag, much like ELLIPSIS or
>NORMALIZE_WHITESPACE.  Tim has given me a few pointers on improvements
>to make, which I'll work on this week.
>
>Thoughts/questions?

It would be nice if tracebacks in the footnote show the invoking context, 
so that if a footnote is invoked from more than one place, you'll be able 
to tell which one from any errors that occur.  I haven't looked at the 
code, so perhaps you've already done this.

My other thought would be that having a patch that works against the 2.5 
version of doctest would be good, as 2.5 has fixes to make doctest work 
with zipped (or egged) doctest files.

Apart from those two comments, it sounds like an interesting idea.