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

[Martin Aspeli]

Martijn Faassen wrote:
> 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?

We've had good success with 
http://pypi.python.org/pypi/collective.recipe.sphinxbuilder

And also http://pypi.python.org/pypi/repoze.sphinx.autointerface for 
interface docs

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

Yay :)

Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book