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

[Martin Aspeli]

Martijn Faassen wrote:
> 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 can't really remember what answers we gave, but  I know we ran it once 
and from then on we've been able to do ./bin/sphinx to rebuild from reST 
sources.

The quickstart thing is only necessary when you start a new project, so 
you should only use it once per package.

> * 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).

Yeah, I saw that one, but had the same conclusion.

> * 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,...

This is what we have in our (project) buildout:

[sphinx]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs/source
build = ${buildout:directory}/docs/output
eggs =
     ${eggs:main}
     repoze.sphinx.autointerface

${eggs:main} is a list of eggs that make up our project's main 
dependencies. We include them so that we can get the automatically 
generated documentation to work.

Martin


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