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