turn on warning-as-error flag for doc build

Change-Id: I5566cfa09dac8dec7a1bc32d95b42d5b136d726f
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

2 files changed, 34 insertions, 18 deletions

diff --git a/doc/source/user/features.rst b/doc/source/user/features.rst
index 7eb88e9..2a4c25c 100644
--- a/doc/source/user/features.rst
+++ b/doc/source/user/features.rst
@@ -81,7 +81,8 @@ Sphinx documentation setups are altered to generate man pages by default. They
 also have several pieces of information that are known to setup.py injected
 into the sphinx config.
 
-See the pbr_ section for details on configuring your project for autodoc.
+See the :ref:`pbr-setup-cfg` section of the configuration file for
+details on configuring your project for autodoc.
 
 Requirements
 ------------
@@ -101,7 +102,8 @@ If you want to have a different package list for Python 3 then just drop a
 `requirements-py3.txt` and it will be used instead.
 
 Finally, it is possible to specify groups of optional dependencies, or
-`"extra" requirements`_, in your `setup.cfg` rather than `setup.py`.
+:ref:`"extra" requirements <extra-requirements>`, in your `setup.cfg`
+rather than `setup.py`.
 
 long_description
 ----------------
diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst
index 93ad043..9f7e6d6 100644
--- a/doc/source/user/using.rst
+++ b/doc/source/user/using.rst
@@ -39,7 +39,11 @@ setup.cfg
 The `setup.cfg` file is an ini-like file that can mostly replace the `setup.py`
 file. It is based on the distutils2_ `setup.cfg` file. A simple sample can be
 found in `pbr`'s own `setup.cfg` (it uses its own machinery to install
-itself)::
+itself):
+
+.. _distutils2: http://alexis.notmyidea.org/distutils2/setupcfg.html
+
+::
 
     [metadata]
     name = pbr
@@ -80,13 +84,13 @@ itself)::
 `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
+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.
+``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
-__ http://www.sphinx-doc.org/en/stable/setuptools.html
+.. _setuptools commands: https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
+.. _Babel: http://babel.pocoo.org/en/latest/setup.html
+.. _setuptools: http://www.sphinx-doc.org/en/stable/setuptools.html
 
 .. note::
 
@@ -151,6 +155,8 @@ using three fundamental keys: ``packages``, ``namespace_packages``, and
   this could be the actual system-wide `/etc` directory or just a top-level
   `etc` subdirectory of a virtualenv.
 
+.. _pbr-setup-cfg:
+
 pbr
 ~~~
 
@@ -166,8 +172,10 @@ The ``pbr`` section controls `pbr` specific options and behaviours.
 ``autodoc_tree_excludes``
 
   A list of modules to exclude when building documentation using
-  `sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man
-  page`_ for more information.
+  `sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the
+  `sphinx-apidoc man page`_ for more information.
+
+.. _sphinx-apidoc man page: http://sphinx-doc.org/man/sphinx-apidoc.html
 
 ``autodoc_index_modules``
 
@@ -197,6 +205,8 @@ The ``pbr`` section controls `pbr` specific options and behaviours.
    set. See the `Sphinx build configuration file`_ documentation for more
    information on configuring Sphinx.
 
+.. _Sphinx build configuration file: http://sphinx-doc.org/config.html
+
 .. versionchanged:: 2.0
 
    The ``pbr`` section used to take a ``warnerrors`` option that would enable
@@ -211,7 +221,7 @@ 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 generation of module documentation using the apidoc tool
 
 - Automatic configuration of the `project`, `version` and `release` settings
   using information from `pbr` itself
@@ -246,7 +256,7 @@ option.
   is.
 
 For information on the remaining options, refer to the `Sphinx
-documentation`__. In addition, the ``autodoc_index_modules``,
+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.
@@ -257,14 +267,13 @@ of the automatic module documentation generation.
    page output. This is no longer the case, and you should explicitly set
    ``builders`` to ``html man`` if you wish to retain this behavior.
 
-__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
-__ http://www.sphinx-doc.org/en/stable/setuptools.html
+.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
 
 entry_points
 ~~~~~~~~~~~~
 
 The ``entry_points`` section defines entry points for generated console scripts
-and python libraries. This is actually provided by `setuptools`__ but is
+and python libraries. This is actually provided by setuptools_ but is
 documented here owing to its importance.
 
 The general syntax of specifying entry points is a top level name indicating
@@ -284,8 +293,6 @@ installed for `pbr.config.drivers`, one called `plain` which maps to the
 `Plain` class in `pbr.cfg.driver` and one called `fancy` which maps to the
 `Fancy` class in `pbr.cfg.driver`.
 
-__ https://setuptools.readthedocs.io/en/latest/setuptools.html#options
-
 Requirements
 ------------
 
@@ -305,6 +312,8 @@ Only the first file found is used to install the list of packages it contains.
    The 'requirements-pyN.txt' file is deprecated - 'requirements.txt' should
    be universal. You can use `Environment markers`_ for this purpose.
 
+.. _extra-requirements:
+
 Extra requirements
 ~~~~~~~~~~~~~~~~~~
 
@@ -312,6 +321,9 @@ Groups of optional dependencies, or `"extra" requirements`_, can be described
 in your `setup.cfg`, rather than needing to be added to `setup.py`. An example
 (which also demonstrates the use of environment markers) is shown below.
 
+.. _"extra" requirements:
+ https://www.python.org/dev/peps/pep-0426/#extras-optional-dependencies
+
 Environment markers
 ~~~~~~~~~~~~~~~~~~~
 
@@ -321,6 +333,9 @@ on the environment the installer is running in. They can be added to
 requirements in the requirements file, or to extras defined in `setup.cfg`,
 but the format is slightly different for each.
 
+.. _conditional dependencies:
+ https://www.python.org/dev/peps/pep-0426/#environment-markers
+
 For ``requirements.txt``::
 
     argparse; python_version=='2.6'
@@ -388,6 +403,5 @@ produce a coverage report.  ``--coverage-package-name`` can be used to
 modify or narrow the packages traced.
 
 .. _d2to1: https://pypi.python.org/pypi/d2to1
-.. _distutils2: https://pypi.python.org/pypi/Distutils2
 .. _PEP 426: http://legacy.python.org/dev/peps/pep-0426/
 .. _OpenStack: https://www.openstack.org/