How to configure buildout to create sphinx documentation using bin/sphinxbuilder

Question

In my buildout.cfg file i have such code:

parts =
    ...
    sphinxbuilder

next in same file:

eggs=
   ...
   jinja2
   markupsafe
   sphinx

and then, at the end of file:

[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs-src
build = ${buildout:directory}/docs

I do:

bin/buildout

which gives output (in general: OK):

Updating sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..

In eggs folder I have Sphinx eeg.

After buildout, under project directory I have one, new catalog: docs. then I run command:

bin/sphinx-quickstart

and as root path for the documentation I set docs

then I edit docs/conf.py and uncomment

sys.path.insert(0, os.path.abspath('.'))

I run command bin/sphinxbuilder and get error:

Makefile:12: *** The 'sphinx-build' command was not found. 
Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the 'sphinx-build' executable.
Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/. Stop.

Main problems: (1) How to get sphinx working automaticly with buildout? (2) How to set right path to project modules (apps) in .rst files? (3) Where to put conf.py file?

Bitternut

are you working on Windows? There's a bug in the 0.8.2 py27 collective.recipe.sphinxbuilder egg which causes an error for me (line 146 in the sphinxbuilder/__init__.py) which prevents me from building out. I am still able to use the other scripts, but using "parts=sphinxbuilder" as in their docs does not work correctly – Winnebago

No, on Linux. Thank You. – Repp

Answer 1

On windows here, but I seem to recall a similar issue.

extending the following cfg ensures two things: 1) all entrypoints we generate have access to the sphinx eggs 2) parts which rely on the sphinx entrypoints will be executed -after- those entrypoints are generated

[sphinx]
eggs = 
    sphinx
    <if you have theme eggs or other extensions, put em here>

parts =
    sphinx.console_scripts

[sphinx.console_scripts]
recipe = zc.recipe.egg
dependent-scripts = true
eggs = 
    ${sphinx.eggs}
    ${buildout:eggs}

Using this, you can also add parts that rely on the build/apidoc executables and your documentation generation becomes part of a one-click buildout:

[sphinx.apidoc]
recipe = plone.recipe.command
command = ${buildout:bin-directory}\sphinx-apidoc.exe <all your flags/settiongs based on buildout>

Winnebago