Martijn Faassen wrote:
> Martin Aspeli wrote:
> [snip]
>> We've had good success with
> 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 

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:

recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs/source
build = ${buildout:directory}/docs/output
eggs =

${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.


Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See

Zope-Dev maillist  -
**  No cross posts or HTML encoding!  **
(Related lists - )

Reply via email to