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

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

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'
 

doc/source/reference/index.rst

@@ -7,4 +7,4 @@ Reference
 .. toctree::
    :maxdepth: 2
 
-   api/modules
+   Modules <api/modules>

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