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 _______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )