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
This commit is contained in:
Stephen Finucane 2017-02-27 12:21:01 +00:00
parent 028f82e6a7
commit 72e8e42a34
6 changed files with 20 additions and 100 deletions

View File

@ -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.

View File

@ -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']

View File

@ -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)

View File

@ -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 = [

View File

@ -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

View File

@ -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