Stop using 'warnerrors'

This legacy option provided the ability to fail on doc warnings.
However, this functionality is broken in recent releases and now exists
in Sphinx itself (since 1.5.0). Rather that fixing it and causing a
whole load of doc build errors introduced in the time since this option
was broken, remove it, preferring the new Sphinx option instead.

This allows us to remove a lot of test code which is essentially testing
Sphinx functionality only now, based on the assumption that Sphinx do
adequate testing themselves.

Change-Id: Ia4b6adefcd437cb1ceb4558b004c17359df2486d

6 files changed, 20 insertions, 100 deletions

diff --git a/doc/source/compatibility.rst b/doc/source/compatibility.rst
index c170dd2..868ac75 100644
--- a/doc/source/compatibility.rst
+++ b/doc/source/compatibility.rst
@@ -49,20 +49,10 @@ Recommended setup.py
 Sphinx
 ======
 
-.. _sphinx-1.4:
+.. _sphinx-1.5:
 
-Version 1.4.0 and 1.4.1
------------------------
+Version 1.5.0+
+--------------
 
-Sphinx added new warnings to version 1.4.0 to warn if a directive, role, or
-node exists and is being overridden.  These extensions are registered to
-global values, and as such, executing multiple builders in a single python
-process triggers these warnings as they were loaded during the first run.
-In version 1.4.2 sphinx added the ability to silence these warnings, and as
-such we silence these warnings on sphinx invocations after the first run.
-
-With version 1.4.0 and 1.4.1 we are unable to silence these warnings, and as
-such, a warnings is printed, and sphinx will fail if running with warnerrors,
-or print warnings.
-
-To silence these warnings upgrade Sphinx to 1.4.2 or greater.
+The ``warning-is-error`` flag is only supported by Sphinx 1.5 and will cause
+errors when used with older versions.
diff --git a/pbr/builddoc.py b/pbr/builddoc.py
index c267af2..f51b283 100644
--- a/pbr/builddoc.py
+++ b/pbr/builddoc.py
@@ -120,7 +120,7 @@ class LocalBuildDoc(setup_command.BuildDoc):
             cmd = ['apidoc', '.', '-H', 'Modules', '-o', source_dir]
             apidoc.main(cmd + self.autodoc_tree_excludes)
 
-    def _sphinx_run(self, warnerrors):
+    def _sphinx_run(self):
         if not self.verbose:
             status_stream = cStringIO.StringIO()
         else:
@@ -145,21 +145,14 @@ class LocalBuildDoc(setup_command.BuildDoc):
                 getattr(sphinx_config, 'man_pages', '')) == 0:
             return
         if self.sphinx_initialized:
-            if sphinx_ver >= pkg_resources.parse_version('1.4.2'):
-                confoverrides['suppress_warnings'] = [
-                    'app.add_directive', 'app.add_role',
-                    'app.add_generic_role', 'app.add_node']
-            elif sphinx_ver >= pkg_resources.parse_version('1.4.0'):
-                log.warn("[pbr] WARN: Sphinx versions 1.4.0 and 1.4.1 raise "
-                         "warnings during this run and will cause warnerrors "
-                         "to fail.  For more information see: "
-                         "http://docs.openstack.org/developer/pbr/"
-                         "compatibility.html#sphinx-1.4")
+            confoverrides['suppress_warnings'] = [
+                'app.add_directive', 'app.add_role',
+                'app.add_generic_role', 'app.add_node']
         app = application.Sphinx(
             self.source_dir, self.config_dir,
             self.builder_target_dir, self.doctree_dir,
             self.builder, confoverrides, status_stream,
-            freshenv=self.fresh_env, warningiserror=warnerrors)
+            freshenv=self.fresh_env, warningiserror=self.warning_is_error)
         self.sphinx_initialized = True
 
         try:
@@ -190,8 +183,6 @@ class LocalBuildDoc(setup_command.BuildDoc):
         auto_index = options.get_boolean_option(option_dict,
                                                 'autodoc_index_modules',
                                                 'AUTODOC_INDEX_MODULES')
-        warnerrors = options.get_boolean_option(option_dict, 'warnerrors',
-                                                'WARNERRORS')
         if not os.getenv('SPHINX_DEBUG'):
             # NOTE(afazekas): These options can be used together,
             # but they do a very similar thing in a different way
@@ -206,7 +197,7 @@ class LocalBuildDoc(setup_command.BuildDoc):
         for builder in self.builders:
             self.builder = builder
             self.finalize_options()
-            self._sphinx_run(warnerrors)
+            self._sphinx_run()
 
     def initialize_options(self):
         # Not a new style class, super keyword does not work.
@@ -219,6 +210,7 @@ class LocalBuildDoc(setup_command.BuildDoc):
     def finalize_options(self):
         # Not a new style class, super keyword does not work.
         setup_command.BuildDoc.finalize_options(self)
+
         # Handle builder option from command line - override cfg
         option_dict = self.distribution.get_option_dict('build_sphinx')
         if 'command line' in option_dict.get('builder', [[]])[0]:
@@ -226,6 +218,7 @@ class LocalBuildDoc(setup_command.BuildDoc):
         # Allow builders to be configurable - as a comma separated list.
         if not isinstance(self.builders, list) and self.builders:
             self.builders = self.builders.split(',')
+
         self.project = self.distribution.get_name()
         self.version = self.distribution.get_version()
         self.release = self.distribution.get_version()
@@ -238,6 +231,10 @@ class LocalBuildDoc(setup_command.BuildDoc):
             self.autodoc_tree_excludes = option_dict[opt][1]
             self.ensure_string_list(opt)
 
+        # handle Sphinx < 1.5.0
+        if not hasattr(self, 'warning_is_error'):
+            self.warning_is_error = False
+
 
 class LocalBuildLatex(LocalBuildDoc):
     builders = ['latex']
diff --git a/pbr/tests/test_integration.py b/pbr/tests/test_integration.py
index 4a4d230..8e96f21 100644
--- a/pbr/tests/test_integration.py
+++ b/pbr/tests/test_integration.py
@@ -267,34 +267,3 @@ class TestLTSSupport(base.BaseTestCase):
         # this particular combination of setuptools and pip.
         self._run_cmd(bin_python, ['-m', 'pip', 'install', pbr],
                       cwd=venv.path, allow_fail=False)
-
-
-class TestSphinxWarnErrors(base.BaseTestCase):
-    sphinx14warning = "[pbr] WARN: Sphinx versions 1.4.0 and 1.4.1 raise"
-    scenarios = [
-        ('sphinxEL6', {'module': 'sphinx==0.6.6'}),
-        ('sphinxWheezyEL7', {'module': 'sphinx==1.1.3'}),
-        ('sphinxJessie', {'module': 'sphinx==1.2.3'}),
-        ('sphinx<1.3', {'module': 'sphinx<1.3.0'}),
-        ('sphinx1.3x', {'module': 'sphinx<1.4.0>=1.3.0'}),
-        ('sphinx1.4.1', {'module': 'sphinx==1.4.1',
-                         'failure': sphinx14warning}),
-        ('sphinx1.4.2', {'module': 'sphinx==1.4.2'}),
-        ('sphinx-latest', {'module': 'sphinx'}),
-    ]
-
-    @testtools.skipUnless(
-        os.environ.get('PBR_INTEGRATION', None) == '1',
-        'integration tests not enabled')
-    def test_sphinx_runs(self):
-        venv = self.useFixture(test_packaging.Venv('sphinx'))
-        bin_python = venv.python
-        self._run_cmd(bin_python, ['-m', 'pip', 'install', self.module],
-                      cwd=venv.path, allow_fail=False)
-        _, err, ret = self._run_cmd(bin_python, ['setup.py', 'build_sphinx'],
-                                    cwd=self.package_dir, allow_fail=True)
-        if hasattr(self, 'failure'):
-            self.assertNotEqual(0, ret)
-            self.assertIn(self.failure, err)
-        else:
-            self.assertEqual(0, ret)
diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py
index 2f19881..0754a8d 100644
--- a/pbr/tests/test_setup.py
+++ b/pbr/tests/test_setup.py
@@ -260,9 +260,6 @@ class BaseSphinxTest(base.BaseTestCase):
         if hasattr(self, 'has_opt') and self.has_opt:
             options = self.distr.command_options["pbr"]
             options["autodoc_index_modules"] = ('setup.cfg', self.autodoc)
-        if hasattr(self, 'warnerrors') and self.warnerrors:
-            options = self.distr.command_options["pbr"]
-            options["warnerrors"] = ('setup.cfg', 'true')
 
 
 class BuildSphinxTest(BaseSphinxTest):
@@ -283,13 +280,6 @@ class BuildSphinxTest(BaseSphinxTest):
          dict(has_opt=False, autodoc='False', has_autodoc=False)),
     ]
 
-    scenarios = testscenarios.scenarios.multiply_scenarios(
-        scenarios,
-        [
-            ('warnerrors', dict(warnerrors=True)),
-            ('nowarnerrors', dict(warnerrors=False))
-        ])
-
     def test_build_doc(self):
         build_doc = packaging.LocalBuildDoc(self.distr)
         build_doc.run()
@@ -375,30 +365,6 @@ class BuildSphinxTest(BaseSphinxTest):
         self.assertEqual(["builder1", "builder2"], build_doc.builders)
 
 
-class WarnErrorSphinxTest(BaseSphinxTest):
-
-    def setUp(self):
-        self.warnerrors = True
-        super(WarnErrorSphinxTest, self).setUp()
-
-    def testWarnErrors(self):
-        """Ensure when warnerror is used, we pass warningiserror true"""
-        self.app_init_executed = False
-
-        def app_init(appSelf, *args, **kwargs):
-            self.assertTrue('warningiserror' in kwargs)
-            self.assertIsInstance(kwargs['warningiserror'], bool)
-            self.assertTrue(kwargs['warningiserror'])
-            appSelf.build = lambda *a, **b: None
-            self.app_init_executed = True
-
-        self.useFixture(fixtures.MonkeyPatch(
-            "sphinx.application.Sphinx.__init__", app_init))
-        build_doc = packaging.LocalBuildDoc(self.distr)
-        build_doc.run()
-        self.assertTrue(self.app_init_executed)
-
-
 class ParseRequirementsTestScenarios(base.BaseTestCase):
 
     versioned_scenarios = [
diff --git a/pbr/tests/testpackage/setup.cfg b/pbr/tests/testpackage/setup.cfg
index a6d127a..242c9c6 100644
--- a/pbr/tests/testpackage/setup.cfg
+++ b/pbr/tests/testpackage/setup.cfg
@@ -55,6 +55,3 @@ commands = pbr_testpackage._setup_hooks.test_command
 [build_ext]
 #pre-hook.test_pre_hook = pbr_testpackage._setup_hooks.test_pre_hook
 #post-hook.test_post_hook = pbr_testpackage._setup_hooks.test_post_hook
-
-[pbr]
-warnerrors = true
diff --git a/setup.cfg b/setup.cfg
index 6640a38..a8d63d1 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -33,7 +33,6 @@ setup-hooks =
     pbr.hooks.setup_hook
 
 [pbr]
-warnerrors = True
 autodoc_tree_index_modules = True
 autodoc_tree_excludes =
    setup.py
@@ -50,9 +49,11 @@ console_scripts =
     pbr = pbr.cmd.main:main
 
 [build_sphinx]
-all_files = 1
+all-files = 1
 build-dir = doc/build
 source-dir = doc/source
+# enable the below once Sphinx is bumped to 1.5.0+ in g-r
+# warning-is-error = 1
 
 [wheel]
 universal = 1