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?
I just use it out of the box after generating some files using "sphinx-quickstart". I suspect just changing the resulting Makefile alias from: SPHINXBUILD = sphinx-build To: SPHINXBUILD = ../../../bin/sphinx-build .. or so, for some buildout usage would work just fine. > 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? Python samples in Sphinx docs are generated like so: .. code-block:: python a == 1 I did a bit of fooling around with Manuel, because I wanted to make sure that the code blocks in my documentation actually worked, but I wound up in a place where I use Manuel to check only the *syntax* of a subets of the Sphinx code blocks I use. It will do this right out of the box if you read the Manuel docs But I couldn't really figure out a way to do the moral equivalent of this: .. code-block:: python a == 1 .. manuel-expect: True Maybe I missed it. But even so, having Manuel to check even the syntax of code blocks is really useful; I found a couple of errors. > Ideas and opinions? This will also help me write the "writing Zope > Toolkit documentation" document. :) - C _______________________________________________ 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 )