Gary Poster had a really good idea a couple weeks ago: teach doctest
about ReST-style footnotes. I implemented it over the weekend and
brought it to Tim Peter's attention today. Tim generally liked the idea
and suggested I bring it up on python-dev, which I have.
Here's the idea: when a footnote is referenced in prose, execute the
code associated with the footnote at that point. For example:
After initializing the system [#init]_ it is possible to retrieve status
'good to go'
[snip some of the doctest]
.. [#init] Initialize the system:
>>> system = System()
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.
I'd like to merge the branch to zope.testing in the next few days.
Senior Software Engineer
Zope3-dev mailing list