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:
parent
028f82e6a7
commit
72e8e42a34
|
@ -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.
|
||||
|
|
|
@ -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']
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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 = [
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue