From cc703f4926e0a4d4dd034176b523923e5a09492a Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 7 Jul 2017 11:14:39 +0100 Subject: [PATCH] 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 --- doc/source/user/using.rst | 17 +++++++++-------- pbr/builddoc.py | 23 +++++++++++++++++------ 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst index 9f7e6d6e..4b08ec4e 100644 --- a/doc/source/user/using.rst +++ b/doc/source/user/using.rst @@ -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 ~~~~~~~~~~~~ diff --git a/pbr/builddoc.py b/pbr/builddoc.py index 5c3a9e65..f6c44d19 100644 --- a/pbr/builddoc.py +++ b/pbr/builddoc.py @@ -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()