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:
parent
c59fad9c88
commit
cc703f4926
|
@ -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
|
||||
~~~~~~~~~~~~
|
||||
|
|
|
@ -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()
|
||||
|
|
Loading…
Reference in New Issue