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

[Laurence Rowe]

On 17 April 2010 10:41, Lennart Regebro <regebro at gmail.com> wrote:
> On Sat, Apr 17, 2010 at 11:18, yuppie <y.2010 at wcm-solutions.de> wrote:
>> 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?
>
> Hm...  As long as you use the >>> syntax and none of the
> ..test-block:: syntax of sphinx, the sphinx docs can be tested as a
> part of the standard testruns, but I guess part of this proposal was
> so we could easily use the testblock syntax as it has the possibility
> to hide setup etc easier. And then I don't know the best way to
> integrate it, but it would definitely be a drawback if you need two
> different testruns to run all the tests...
>
> Also I think it should be the responsibility of the one who does a
> release to make sure that we can build HTML docs and that the
> formatting isn't *too* broken.
> Preferably these docs should also be uploaded to packages.python.org,
> maybe there can be a makefile step for that in the docs?

It's important that documentation is tested as part of the standard
test run, that means when you change something you know to update the
docs. repoze.bfg seemed to make an attempt at this, though it is
currently disabled.
http://svn.repoze.org/repoze.bfg/trunk/repoze/bfg/tests/test_docs.py

Laurence