[Python-Dev] Doctest and Footnotes

[Phillip J. Eby]

At 02:12 PM 7/11/2006 -0400, Alexander Belopolsky wrote:
>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.

A common use case for doctests in Zope is separate text files that are used 
as documentation.  I also use this approach for generating documentation 
myself, e.g.:

http://chandler.osafoundation.org/docs/0.7/parcel-schema-guide.html
http://chandler.osafoundation.org/docs/0.7/running-code-at-startup.html
http://peak.telecommunity.com/DevCenter/BytecodeAssembler

To name just a few.