From 6507ff752ea0877cd28c0a922e49e2cd05faf5c2 Mon Sep 17 00:00:00 2001
From: Sean McGinnis <sean.mcginnis@huawei.com>
Date: Wed, 21 Mar 2018 17:10:47 -0500
Subject: [PATCH] Avoid use of autodoc_tree_index_modules

Changes doc jobs to not user the pbr autodoc_tree_index_modules
directive to generate module documentation by using the new
sphinxcontrib.apidoc extension.

Depends-On: https://review.openstack.org/560379/
Change-Id: Idc84455cf78b6114b31109b7ef9ab3ac9c97e136
---
 doc/requirements.txt           |  1 +
 doc/source/conf.py             | 13 ++++++++-----
 doc/source/reference/index.rst |  2 +-
 setup.cfg                      | 13 -------------
 4 files changed, 10 insertions(+), 19 deletions(-)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 6098fcba..95f33df8 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -9,6 +9,7 @@ reno>=2.5.0 # Apache-2.0
 python-memcached>=1.56 # PSF
 pymongo!=3.1,>=3.0.2 # Apache-2.0
 etcd3gw>=0.2.0 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0  # BSD
 
 # For autodoc builds
 mock>=2.0.0 # BSD
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 4fb914e3..a4a47c02 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -21,7 +21,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinxcontrib.apidoc',
     'sphinx.ext.intersphinx',
     'openstackdocstheme',
     'oslo_config.sphinxext',
@@ -32,13 +32,16 @@ repository_name = 'openstack/oslo.cache'
 bug_project = 'oslo.cache'
 bug_tag = ''
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../oslo_cache'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'tests'
+]
+
 # Must set this variable to include year, month, day, hours, and minutes.
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
-
 # The suffix of source filenames.
 source_suffix = '.rst'
 
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 65d9a527..a8386cf5 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -7,4 +7,4 @@ Reference
 .. toctree::
    :maxdepth: 2
 
-   api/modules
+   Modules <api/modules>
diff --git a/setup.cfg b/setup.cfg
index 79b7b70b..e2845b2f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -40,19 +40,6 @@ mongo =
 etcd3gw =
   etcd3gw>=0.2.0 # Apache-2.0
 
-[pbr]
-autodoc_tree_index_modules = True
-api_doc_dir = reference/api
-
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-warning-is-error = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = oslo_cache/locale
 domain = oslo_cache