On Sat, Jan 2, 2010 at 2:21 PM, Martijn Faassen <faassen@startifact.com> wrote:
It'd also be interesting to explore using Manuel - how would one add manuel-based testing to a Sphinx documentation tree? I'd like to give the priority to testing documentation samples as opposed to doctest-driven testing.
The Manuel docs use both Sphinx and Manuel, so should be good examples. I don't use a Sphinx recipe at the moment though. I just used zc.recipe.egg:script. See [sphinx-docs-html] and [build-docs] in the Manuel buildout.ini for details (http://svn.zope.org/*checkout*/manuel/trunk/buildout.cfg).
I also want to be careful: sometimes the doctest setup fluff tends to distract from clear documentation, and sometimes the effort in composing doctests will slow down writing documentation.
You can hide setup code using Manuel: http://packages.python.org/manuel/#invisible-code-blocks.
I'd therefore want manuel-tested sample code to be incremental. I want to be able to start out with purely untested sample code and then gradually convert *some* samples over to Manuel. How could we support that pattern?
Manuel lets you specify which pieces of code should be run and which should be ignored (http://packages.python.org/manuel/#ignore). -- Benji York