[Zope-dev] patterns for using sphinx with the Zope Toolkit?

[Benji York]

On Sat, Jan 2, 2010 at 2:21 PM, Martijn Faassen <faassen at 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