[Zope-dev] RFC: Proposed new style for documenting and testing ZTK packages

[yuppie]

Hi!


Tres Seaver wrote:
> The refactoring I would like to see happen is to move the main narrative
> documentation into a separate, Sphinx-driven 'docs' directory in each
> ZTK package.  As part of this move, we can start adding some of the
> really nice Sphinx features (cross references, indexing, auto-generation
> of API reference information, etc.).
>
> We can still leave the "main line" of the code illustrated using
> doctest-style blocks:  Sphinx has nice support for testing those blocks
> *while building the docs*.
[...]
> Thoughts?

+1 in general, but I'm concerned about one thing:

How can we make sure docs and code don't get out of sync? Do we have to 
run unittests *and* build the docs before each checkin? Will someone 
make sure buildbots and nightly tests report broken docs as well?


Cheers,

	Yuppie