From cc703f4926e0a4d4dd034176b523923e5a09492a Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 7 Jul 2017 11:14:39 +0100 Subject: 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 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst index 9f7e6d6..4b08ec4 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 ~~~~~~~~~~~~ -- cgit v1.2.1