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 _______________________________________________ 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 )