Merge "Deprecate support for Sphinx < 1.6"

This commit is contained in:
Jenkins 2017-10-09 17:33:49 +00:00 committed by Gerrit Code Review
commit c45687fb9b
2 changed files with 26 additions and 14 deletions

View File

@ -230,16 +230,15 @@ following:
.. note::
Sphinx 1.6 adds support for multiple builders using the default `builder`
option. You should refer to this file for more information.
Only applies to Sphinx < 1.6. See documentation on ``builders`` below.
The version of ``build_sphinx`` provided by `pbr` provides a single additional
option.
``builders``
A space or comma separated list of builders to run. For example, to build
both HTML and man page documentation, you would define the following in your
A comma separated list of builders to run. For example, to build both HTML
and man page documentation, you would define the following in your
`setup.cfg`:
.. code-block:: ini
@ -249,11 +248,13 @@ option.
source-dir = doc/source
build-dir = doc/build
all-files = 1
warning-is-error = 1
``source_dir``
.. deprecated:: 3.2.0
The path to the source directory where the Sphinx documentation tree
is.
Sphinx 1.6+ adds support for specifying multiple builders in the default
``builder`` option. You should use this option instead. Refer to the
`Sphinx documentation`_ for more information.
For information on the remaining options, refer to the `Sphinx
documentation`_. In addition, the ``autodoc_index_modules``,
@ -267,7 +268,7 @@ of the automatic module documentation generation.
page output. This is no longer the case, and you should explicitly set
``builders`` to ``html man`` if you wish to retain this behavior.
.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/setuptools.html
entry_points
~~~~~~~~~~~~

View File

@ -193,18 +193,29 @@ class LocalBuildDoc(setup_command.BuildDoc):
is_multibuilder_sphinx = version.SemanticVersion.from_pip_string(
sphinx.__version__) >= version.SemanticVersion(1, 6)
if self.builders != ['html'] and is_multibuilder_sphinx:
self.builder = self.builders
# TODO(stephenfin): Remove support for Sphinx < 1.6 in 4.0
if not is_multibuilder_sphinx:
log.warning('[pbr] Support for Sphinx < 1.6 will be dropped in '
'pbr 4.0. Upgrade to Sphinx 1.6+')
# TODO(stephenfin): Remove this at the next MAJOR version bump
if self.builders != ['html']:
log.warning("[pbr] Sphinx 1.6 added native support for "
"specifying multiple builders in the "
"'[sphinx_build] builder' configuration option, "
"found in 'setup.cfg'. As a result, the "
"'[sphinx_build] builders' option has been "
"deprecated and will be removed in pbr 4.0. Migrate "
"to the 'builder' configuration option.")
if is_multibuilder_sphinx:
self.builder = self.builders
# TODO(stephenfin): Deprecate this functionality once we decide on
# Sphinx 1.6, which includes a similar feature, in g-r
# https://github.com/sphinx-doc/sphinx/pull/3476
if is_multibuilder_sphinx:
# Sphinx >= 1.6
return setup_command.BuildDoc.run(self)
# Sphinx < 1.6
for builder in self.builders:
for builder in self.builder:
self.builder = builder
self.finalize_options()
self._sphinx_run()