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>

doc/source/user/features.rst

@@ -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`.

doc/source/user/using.rst

@@ -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/

pbr/builddoc.py

@@ -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)