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