[Zope-dev] Why I dislike narrative doctests

[Kent Tenney]

On Fri, Apr 25, 2008 at 10:11 AM, Kent Tenney <ktenney at gmail.com> wrote:
>
> On Fri, Apr 25, 2008 at 9:39 AM, Jim Fulton <jim at zope.com> wrote:
>  >
>  >  On Apr 25, 2008, at 10:20 AM, Kent Tenney wrote:
>  >
>  > > However, as Sphinx lowers the barrier to cross-referencing,
>  > >
>  >
>  >  Sounds like I need to check that out. :)
>  >
>  >
>  >
>  > > they will become
>  > > important as link destinations from 'real' documentation.
>  > >
>  >
>  >
>  >  Maaaybe.  I like doctests for readability even if they aren't
>  > documentation.  I'd be hesitant to link to d=non-documentation from
>  > documentation.
>
>  I think even non-documentation doctests are documentation since they
>  demonstrate correct usage. They need to be explained in the linking
>  document, but they are invaluable as examples.
>
>  Seems like a natural separation of concerns.

To make this work well, the doctests would want to have some
markup added to identify specific tests, so the link would be to
the test, not the file.

This would be a good entry level chore for folks wanting to contribute.

>
>
>
>  >
>  >
>  >
>  >  Jim
>  >
>  >  --
>  >  Jim Fulton
>  >  Zope Corporation
>  >
>  >
>  >
>