openstack
/
pbr
Code Issues Proposed changes

Deprecate support for Sphinx < 1.6 

We don't want to support older versions of Sphinx forever. While
OpenStack's global requirements have been bumped to Sphinx 1.6, there
are non-OpenStack users in the wild. Give them a chance to upgrade to
the newer version before we completely remove support.

This also gives us a chance to deprecate the '[sphinx_build] builders'
setuptools option, which is no longer necessary with Sphinx 1.6+. Do
this. The documentation is updated to reflect this (and some references
to a "custom" 'source_dir' option removed, as it's not at all specific
to pbr).

Change-Id: I18bbf693bca2f6e49d822ae2940d2170a2b90ce9
Related-Bug: #1702872
This commit is contained in:
Stephen Finucane 2017-07-07 11:14:39 +01:00
parent c59fad9c88
commit cc703f4926
2 changed files with 26 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/source/user/using.rst
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
~~~~~~~~~~~~

23
pbr/builddoc.py
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()