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?

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>