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

[Martijn Faassen]

Hi there,

I am interested in creating sphinx-driven documentation for Zope Toolkit 
packages. I'd like to maintain the documentation for a package (say, 
zope.component) in that package, in a 'doc' directory.

I'm wondering what experiences people have with maintaining Sphinx docs. 
I've used plain Sphinx before, but are there any buildout recipes people 
recommend, for instance?

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. 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.
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?

Ideas and opinions? This will also help me write the "writing Zope 
Toolkit documentation" document. :)

Regards,

Martijn