doc: Document Sphinx integration

This was briefly detailed before, but the variant of 'build_sphinx'
provided by 'pbr' does a lot for us that should be documented somewhere.

Change-Id: I0b1877c565d7771e7f0dfdf9198ff41bcd051dec

1 files changed, 60 insertions, 6 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4c80aa6..a7e9775 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -201,6 +201,7 @@ itself)::
     keywords =
         setup
         distutils
+
     [files]
     packages =
         pbr
@@ -209,18 +210,19 @@ itself)::
         etc/init =
             pbr.packaging.conf
             pbr.version.conf
+
     [entry_points]
     console_scripts =
         pbr = pbr.cmd:main
     pbr.config.drivers =
         plain = pbr.cfg.driver:Plain
 
-pbr provides its own section in these documents, ostensibly called `pbr`. Most
-other sections are provided by setuptools and may influence either the build
-itself or the output of various `setuptools commands`__. The remaining sections
-are provided by libraries that provide setuptools extensions, such as
-`extract_mesages` (provided by `Babel`__) or `sphinx_build` (provided by
-`Sphinx`__). Some of these are described below.
+pbr provides its own section in these documents, ostensibly called `pbr`, and
+provides a custom version of Sphinx's `build_sphinx` section. Most other
+sections are provided by setuptools and may influence either the build itself
+or the output of various `setuptools commands`__. The remaining sections are
+provided by libraries that provide setuptools extensions, such as
+`extract_mesages` (provided by `Babel`__). Some of these are described below.
 
 __ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
 __ http://babel.pocoo.org/en/latest/setup.html
@@ -310,6 +312,58 @@ contains `fnmatch` style pattern (e.g. `myapp.tests.*`) to exclude some modules.
    set. See the `Sphinx build configuration file`_ documentation for more
    information on configuring Sphinx.
 
+.. versionchanged:: 2.0
+
+   The ``pbr`` section used to take a ``warnerrors`` option that would enable
+   the ``-W`` (Turn warnings into errors.) option when building Sphinx. This
+   feature was broken in 1.10 and was removed in pbr 2.0 in favour of the
+   ``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+.
+
+build_sphinx
+~~~~~~~~~~~~
+
+The ``build_sphinx`` section is a version of the ``build_sphinx`` setuptools
+plugin provided with Sphinx. This plugin extends the original plugin to add the
+following:
+
+- Automatic generation of module documentation using the apidoc__ tool
+
+- Automatic configuration of the `project`, `version` and `release` settings
+  using information from `pbr` itself
+
+- Support for multiple builders using the ``builders`` configuration option
+
+  .. note::
+
+     Sphinx 1.6 adds support for multiple builders using the default `builder`
+     option. You should refer to this file for more information.
+
+The version of ``build_sphinx`` provided by `pbr` provides a single additional
+option.
+
+``builders``
+
+  A space or comma separated list of builders to run. For example, to build
+  both HTML and man page documentation, you would define the following in your
+  `setup.cfg`:
+
+  .. code-block:: ini
+
+      [build_sphinx]
+      builders = html,man
+      source-dir = doc/source
+      build-dir = doc/build
+      all-files = 1
+
+For information on the remaining options, refer to the `Sphinx
+documentation`__. In addition, the ``autodoc_index_modules``,
+``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and
+``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output
+of the automatic module documentation generation.
+
+__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
+__ http://www.sphinx-doc.org/en/stable/setuptools.html
+
 entry_points
 ~~~~~~~~~~~~