Deprecate 'build_sphinx' integration
We now have a path away from this feature, so let's deprecate it while we can. Change-Id: Idfc34b9085c6da9b8cac24986be5f3bad142d927 Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This commit is contained in:
parent
75bac5d50b
commit
ecbda3076e
@ -256,6 +256,8 @@ __ https://packaging.python.org/tutorials/distributing-packages/#manifest-in
|
||||
Setup Commands
|
||||
--------------
|
||||
|
||||
.. _build_sphinx:
|
||||
|
||||
``build_sphinx``
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -265,6 +267,15 @@ Setup Commands
|
||||
*pbr*-provided package metadata and automatically generate API
|
||||
documentation.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been superseded by the `sphinxcontrib-apidoc`__ (for
|
||||
generation of API documentation) and :ref:`pbr.sphinxext` (for configuration
|
||||
of versioning via package metadata) extensions. It will be removed in a
|
||||
future release.
|
||||
|
||||
__ https://pypi.org/project/sphinxcontrib-apidoc/
|
||||
|
||||
Sphinx can produce auto documentation indexes based on signatures and
|
||||
docstrings of your project but you have to give it index files to tell it to
|
||||
*autodoc* each module: that's kind of repetitive and boring. *pbr* will scan
|
||||
@ -311,6 +322,8 @@ __ https://testrepository.readthedocs.io/en/latest/
|
||||
__ https://nose.readthedocs.io/en/latest/
|
||||
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#test-build-package-and-run-a-unittest-suite
|
||||
|
||||
.. _pbr.sphinxext:
|
||||
|
||||
Sphinx Extension
|
||||
----------------
|
||||
|
||||
@ -325,4 +338,12 @@ Sphinx Extension
|
||||
numbers for documentation. The package does not need to be installed for this
|
||||
to function.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``openstackdocstheme`` Sphinx theme provides similar functionality.
|
||||
This should be preferred for official OpenStack projects. Refer to the
|
||||
`documentation`__ for more information.
|
||||
|
||||
__ https://docs.openstack.org/openstackdocstheme/
|
||||
|
||||
For more information on the extension, refer to :doc:`/user/using`.
|
||||
|
@ -236,6 +236,11 @@ The ``pbr`` section controls *pbr*-specific options and behaviours.
|
||||
are included, but this can be overridden using the ``autodoc_tree_excludes``
|
||||
option.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been replaced by the `sphinxcontrib-apidoc`_ extension.
|
||||
Refer to the :ref:`build_sphinx` overview for more information.
|
||||
|
||||
``autodoc_tree_excludes``
|
||||
A list of modules to exclude when building documentation using
|
||||
``sphinx-apidoc``. Defaults to ``[setup.py]``. Refer to the
|
||||
@ -243,21 +248,41 @@ The ``pbr`` section controls *pbr*-specific options and behaviours.
|
||||
|
||||
__ http://sphinx-doc.org/man/sphinx-apidoc.html
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been replaced by the `sphinxcontrib-apidoc`_ extension.
|
||||
Refer to the :ref:`build_sphinx` overview for more information.
|
||||
|
||||
``autodoc_index_modules``
|
||||
A boolean option controlling whether *pbr* should itself generates
|
||||
documentation for Python modules of the project. By default, all found Python
|
||||
modules are included; some of them can be excluded by listing them in
|
||||
``autodoc_exclude_modules``.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been replaced by the `sphinxcontrib-apidoc`_ extension.
|
||||
Refer to the :ref:`build_sphinx` overview for more information.
|
||||
|
||||
``autodoc_exclude_modules``
|
||||
A list of modules to exclude when building module documentation using *pbr*.
|
||||
*fnmatch* style pattern (e.g. ``myapp.tests.*``) can be used.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been replaced by the `sphinxcontrib-apidoc`_ extension.
|
||||
Refer to the :ref:`build_sphinx` overview for more information.
|
||||
|
||||
``api_doc_dir``
|
||||
A subdirectory inside the ``build_sphinx.source_dir`` where auto-generated
|
||||
API documentation should be written, if ``autodoc_index_modules`` is set to
|
||||
True. Defaults to ``"api"``.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been replaced by the `sphinxcontrib-apidoc`_ extension.
|
||||
Refer to the :ref:`build_sphinx` overview for more information.
|
||||
|
||||
.. note::
|
||||
|
||||
When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may
|
||||
@ -270,6 +295,12 @@ The ``pbr`` section controls *pbr*-specific options and behaviours.
|
||||
|
||||
__ http://sphinx-doc.org/config.html
|
||||
|
||||
.. versionchanged:: 4.2
|
||||
|
||||
The ``autodoc_tree_index_modules``, ``autodoc_tree_excludes``,
|
||||
``autodoc_index_modules``, ``autodoc_exclude_modules`` and ``api_doc_dir``
|
||||
settings are all deprecated.
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
|
||||
The ``pbr`` section used to take a ``warnerrors`` option that would enable
|
||||
@ -293,6 +324,13 @@ The ``pbr`` section controls *pbr*-specific options and behaviours.
|
||||
page output. This is no longer the case, and you should explicitly set
|
||||
``builders`` to ``html man`` if you wish to retain this behavior.
|
||||
|
||||
.. deprecated:: 4.2
|
||||
|
||||
This feature has been superseded by the `sphinxcontrib-apidoc`_ (for
|
||||
generation of API documentation) and :ref:`pbr.sphinxext` (for configuration
|
||||
of versioning via package metadata) extensions. It will be removed in a
|
||||
future release.
|
||||
|
||||
The ``build_sphinx`` section is a version of the ``build_sphinx`` *setuptools*
|
||||
plugin provided with Sphinx. This plugin extends the original plugin to add the
|
||||
following:
|
||||
@ -450,3 +488,4 @@ You should also unset/remove the ``version`` and ``release`` attributes from
|
||||
this file.
|
||||
|
||||
.. _setuptools: http://www.sphinx-doc.org/en/stable/setuptools.html
|
||||
.. _sphinxcontrib-apidoc: https://pypi.org/project/sphinxcontrib-apidoc/
|
||||
|
@ -57,6 +57,9 @@ from pbr import options
|
||||
from pbr import version
|
||||
|
||||
|
||||
_deprecated_options = ['autodoc_tree_index_modules', 'autodoc_index_modules',
|
||||
'autodoc_tree_excludes', 'autodoc_exclude_modules']
|
||||
_deprecated_envs = ['AUTODOC_TREE_INDEX_MODULES', 'AUTODOC_INDEX_MODULES']
|
||||
_rst_template = """%(heading)s
|
||||
%(underline)s
|
||||
|
||||
@ -181,6 +184,23 @@ class LocalBuildDoc(setup_command.BuildDoc):
|
||||
|
||||
def run(self):
|
||||
option_dict = self.distribution.get_option_dict('pbr')
|
||||
|
||||
# TODO(stephenfin): Remove this (and the entire file) when 5.0 is
|
||||
# released
|
||||
warn_opts = set(option_dict.keys()).intersection(_deprecated_options)
|
||||
warn_env = list(filter(lambda x: os.getenv(x), _deprecated_envs))
|
||||
if warn_opts or warn_env:
|
||||
msg = ('The autodoc and autodoc_tree features are deprecated in '
|
||||
'4.2 and will be removed in a future release. You should '
|
||||
'use the sphinxcontrib-apidoc Sphinx extension instead. '
|
||||
'Refer to the pbr documentation for more information.')
|
||||
if warn_opts:
|
||||
msg += ' Deprecated options: %s' % list(warn_opts)
|
||||
if warn_env:
|
||||
msg += ' Deprecated environment variables: %s' % warn_env
|
||||
|
||||
log.warn(msg)
|
||||
|
||||
if git._git_is_installed():
|
||||
git.write_git_changelog(option_dict=option_dict)
|
||||
git.generate_authors(option_dict=option_dict)
|
||||
|
Loading…
Reference in New Issue
Block a user