Set up building the docs, and document how.

buildout.cfg

@@ -18,7 +18,7 @@ parts =
     zopepy
     alltests
     allpy
-    docs
+    sphinx
     checkversions
     wsgi
 sources-dir = develop
@@ -86,10 +86,13 @@ interpreter = allpy
 scripts = allpy
 
 
-[docs]
-recipe = zc.recipe.egg
-eggs = Sphinx
-
+[sphinx]
+recipe = collective.recipe.sphinxbuilder
+build = ${buildout:directory}/docs/_build
+source = ${buildout:directory}/docs
+outputs = html
+script-name = make-docs
+extra-paths = ${buildout:directory}
 
 [checkversions]
 recipe = zc.recipe.egg

docs/INSTALL.rst

@@ -187,3 +187,12 @@ used to automate this whole process.
 
 After installation, refer to :doc:`operation` for documentation on
 configuring and running Zope.
+
+
+Building the documentation with ``Sphinx``
+------------------------------------------
+
+To build the HTML documentation, run the :command:`make-docs` script (installed
+by the buildout)::
+
+   $ bin/make-docs

docs/operation.rst

@@ -4,9 +4,8 @@ Configuring and Running Zope
 .. highlight:: bash
 
 
-Whichever method you used to install Zope and create a server instance (see
-:doc:`INSTALL` and :doc:`INSTALL-buildout`), the end result is configured
-and operated the same way.
+After installing Zope and create a server instance (see :doc:`INSTALL`), the
+end result is configured and operated as follows.
 
 
 Configuring Zope

versions.cfg

@@ -61,6 +61,7 @@ zope.schema = 4.4.2
 zope.traversing = 4.0.0
 
 # Zope2 dependencies
+collective.recipe.sphinxbuilder = 0.8.2
 mechanize = 0.2.5
 repoze.retry = 1.3
 repoze.tm2 = 2.0