Doctests: specify the target readership

Ben Bangert was reacting about zc.buildout doctests, saying that they are hard to read from the PyPI page, and the examples hard to use and follow.

I agree with Ben as these doctests are very hard to read when you are not familiar with zc.buildout testing modules, which provides a set of API the doctests relies on.

But from a developer point of view, adding a feature to such a package is best done through doctests, using zc.buildout.testing goodies. And a developer that is familiar with this package, will find this doctest very useful.

zc.buildout in any case, is trying to structurize its PyPI front page, and push a maximum amount of doc for users, so ... kudos !

I think the problem is more about specifying the target readership.

I would like to point another example that comes in zc.buildout: dependency-links.

The main doctest that appears at PyPI as a light, human-readable section: [][]

And the very same section is continued in a specific doctest that does not appear on the main page:

So what happened here is that the developer specified two kind of readers:
- people that will reach the package through its PyPI page - people that will go deeper in how the package works, through recipes or tutorials

From there I think there's a simple guideline that could be applied to enhance the package documentation when adding a feature:
- resume the feature in the main page (long_description) with examples that does not rely on specific testing API. In other words it should be made of plain english and plain python when needed; - leave doctest that relies on internal testing API as complementary documentation. - define for each doctest its nature (recipe, tutorial, etc)

How could we help people doing such structuration ?

The distutils metadata could be a good place to do it, by adding an extra_doctests list for example, that would contain a list of doctests. From there, PyPI could display the long_description text as usual, and add a "more information section".

Let's take an example:
def _(f)

return open(f).read()

setup('my.package', ...



{'recipe': [_('create_this.txt'),


'tutorial': [_('how_to_use.txt')


From there, PyPI could provide a Table of content, with a structurized documentation, and additional pages for the package, grouped by types (recipe, tutorial) etc. -> Maybe a Sphinx-powered PyPI ? :)

By the way, I have another post related, which tries to summarized good pratices in technical writing :