diff options
| author | Stephen Finucane <sfinucan@redhat.com> | 2017-07-07 11:14:39 +0100 |
|---|---|---|
| committer | Stephen Finucane <sfinucan@redhat.com> | 2017-09-25 16:22:48 +0100 |
| commit | cc703f4926e0a4d4dd034176b523923e5a09492a (patch) | |
| tree | c121b080dd241774af8a138cc2ab2107dd928c99 /doc | |
| parent | c59fad9c883c85af02b663f5c25b297f54f992d1 (diff) | |
| download | pbr-cc703f4926e0a4d4dd034176b523923e5a09492a.tar.gz | |
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
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/user/using.rst | 17 |
1 files changed, 9 insertions, 8 deletions
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 ~~~~~~~~~~~~ |