Follow the new PTI for document build

- Follow new PTI for docs build
- Add sphinxcontrib.apidoc to replace pbr autodoc

REF:
https://governance.openstack.org/tc/reference/project-testing-interface.html
http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Change-Id: Ic66fe4d5488c7777439a416fbf86d37af807804d
Closes-Bug: #1792115

doc/requirements.txt

@@ -4,3 +4,4 @@
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0 # BSD

doc/source/conf.py

@@ -17,10 +17,19 @@
 # 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',
     'openstackdocstheme',
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.apidoc',
 ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../novaclient'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'v2/contrib/*']
+apidoc_separate_modules = True
+
 # The content that will be inserted into the main body of an autoclass
 # directive.
 autoclass_content = 'both'

doc/source/reference/api/index.rst

@@ -104,6 +104,6 @@ Reference
 For more information, see the reference:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 6
 
-   autoindex
+   modules

setup.cfg

@@ -29,21 +29,9 @@ packages =
 console_scripts =
     nova = novaclient.shell:main
 
-[build_sphinx]
-builders = html,man
-all-files = 1
-warning-is-error = 1
-source-dir = doc/source
-build-dir = doc/build
-
 [upload_sphinx]
 upload-dir = doc/build/html
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules = novaclient.tests.* novaclient.v2.contrib.*
-api_doc_dir = reference/api
-
 [compile_catalog]
 domain = novaclient
 directory = novaclient/locale

tox.ini

@@ -46,7 +46,7 @@ deps =
   -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/build
-  sphinx-build -b html doc/source doc/build/html
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
 basepython = python3