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

[Martijn Faassen]

Martin Aspeli wrote:
[snip]
> We've had good success with 
> http://pypi.python.org/pypi/collective.recipe.sphinxbuilder

I'm having trouble with this. I'm trying to set up a "narrative_docs" 
directory in a package but:

* the documentation on collective.recipe.sphinxbuilder pypi talks about 
a bin/sphinxbuilder script. That simply isn't there (the sphinx-build 
and sphinx-quickstart commands are). Ah, I see it is named after my 
section. The documentation didn't say that.

* I'm supposed to run sphinx-quickstart by hand and "answer a few 
questions and choose docs-source as your source folder". I'd like to 
tell about my source folder, but instead it asks me for a "root path for 
the documentation". I cannot directly control the source path at all, 
only whether it is the root path or whether it's in root_path/source.

* I'd prefer it if I ended up with a sphinx quickstart script that got 
preconfigured with the choices I made in buildout anyway, or perhaps 
even run quickstart itself when necessary (but a manual step here is 
okay and perhaps the sanest)
There's also a z3c.recipe.sphinxdoc recipe. This seems to be geared 
towards producing sphinx documentation from doctests within a Python 
package. I think to encourage narrative documentation I'd like to 
separate this documentation from the source tree (though I *would* like 
to have the *option* to use doc tests).

* Do I need to answer 'y' or 'no' to the 'Create Makefile' question and 
a windows command file?

This is definitely frustrating. :) I want to document something about 
this so that people have more guidance and that our ZTK packages have a 
similar documentation structure,...

Regards,

Martijn