zuul/zuul-jobs
Code Issues Proposed changes

Default warning-is-error to True for non-legacy Sphinx projects

Browse Source 
We're trying to move away from the legacy pbr 'build_sphinx' command.
However, without the relevant section in the 'setup.cfg' file, we have
no way to determine if the user wishes to use the '-W'
(warning-is-error) flag when building docs. The current behavior for
this is to default to False, meaning documentation for projects that
previously used the pbr functionality to enable warning-is-error is
liable to slowly break as time passes.

To resolve this, default to True for packages with no [build_sphinx]
section in setup.cfg. This ensures that projects migrating to the new
PTI (which, when fully implemented, involves removing the [build_sphinx]
section from setup.cfg) will be forced to fix any warnings prior to the
migration. However, packages that have not been converted will not be
broken. Only pacakges that have already fully switched over to the new
PTI but which did not have warning-is-error enabled are at risk of
unexpected breakage, but even for those the short-term pain should
ultimately be outweighed by the long-term gain.

Change-Id: I677afef96370ead5a45cba854ba483f18a8d1247
This commit is contained in:
Stephen Finucane 2018-04-06 15:38:32 +01:00
parent 4ea02ec487
commit a258aa9a3b
2 changed files with 10 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
roles/sphinx/README.rst
View File

@ -19,8 +19,10 @@ Run sphinx to generate documentation
.. zuul:rolevar:: sphinx_warning_is_error .. zuul:rolevar:: sphinx_warning_is_error
Whether to treat sphinx build warnings as errors. Defaults to undefined Whether to treat sphinx build warnings as errors. Defaults to the value of
which means to attempt to find the setting in a setup.cfg file. ``[build_sphinx] warning-is-error`` in ``setup.cfg`` if defined, ``False``
if the ``[build_sphinx]`` section is present but the ``warning-is-error``
option is undefined, or ``True`` if the entire section is undefined.
.. zuul:rolevar:: zuul_work_virtualenv .. zuul:rolevar:: zuul_work_virtualenv
:default: ~/.venv :default: ~/.venv

10
roles/sphinx/library/sphinx_check_warning_is_error.py
View File

@ -68,7 +68,7 @@ def main():
) )
project_dir = module.params['project_dir'] project_dir = module.params['project_dir']
warning_is_error = False warning_is_error = True
# TODO(mordred) Remove autodoc_index_modules logic when we get OpenStack # TODO(mordred) Remove autodoc_index_modules logic when we get OpenStack
# projects off of the pbr autoindex # projects off of the pbr autoindex
autodoc_index_modules = False autodoc_index_modules = False
@ -91,9 +91,11 @@ def main():
autodoc_index_modules=autodoc_index_modules, autodoc_index_modules=autodoc_index_modules,
msg="Error reading setup.cfg, defaulting flags to false") msg="Error reading setup.cfg, defaulting flags to false")
if (c.has_section('build_sphinx') and if c.has_section('build_sphinx'):
c.has_option('build_sphinx', 'warning-is-error')): if c.has_option('build_sphinx', 'warning-is-error'):
warning_is_error = c.getboolean('build_sphinx', 'warning-is-error') warning_is_error = c.getboolean('build_sphinx', 'warning-is-error')
else:
warning_is_error = False
if c.has_section('pbr') and c.has_option('pbr', 'autodoc_index_modules'): if c.has_section('pbr') and c.has_option('pbr', 'autodoc_index_modules'):
autodoc_index_modules = c.getboolean('pbr', 'autodoc_index_modules') autodoc_index_modules = c.getboolean('pbr', 'autodoc_index_modules')
if (c.has_section('pbr') and if (c.has_section('pbr') and