Re: RFC: Proposed new style for documenting and testing ZTK packages
yuppie <[email protected]>
| Newsgroups | gmane.comp.web.zope.devel |
|---|---|
| Message-ID | <[email protected]> |
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 _______________________________________________ Zope-Dev maillist - [email protected] https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )