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

Depends-On: https://review.openstack.org/#/c/559334/
Change-Id: I1d5f01cf49f36567f5a891c69c7269d3e966b9c5

doc/requirements.txt

@@ -1,20 +1,8 @@
 # The order of packages is significant, because pip processes them in the order
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
-
-# required to build documentation
 openstackdocstheme>=1.18.1 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 reno>=2.5.0 # Apache-2.0
-fixtures>=3.0.0 # Apache-2.0/BSD
 os-api-ref>=1.4.0 # Apache-2.0
-testtools>=2.2.0 # MIT
-WebTest>=2.0.27 # MIT
-mock>=2.0.0 # BSD
-freezegun>=0.3.6 # Apache-2.0
-flake8-docstrings==0.2.1.post1 # MIT
-oslotest>=3.2.0 # Apache-2.0
-oslo.db[fixtures,mysql,postgresql]>=4.27.0 # Apache-2.0
-lxml!=3.7.0,>=3.4.1 # BSD
-pyldap>=2.4.20 # PSF
-ldappool>=2.0.0 # MPL

doc/source/conf.py

@@ -45,8 +45,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',
-              'sphinx.ext.coverage',
+extensions = ['sphinx.ext.coverage',
               'sphinx.ext.viewcode',
               'oslo_config.sphinxconfiggen',
               'oslo_config.sphinxext',
@@ -54,8 +53,18 @@ extensions = ['sphinx.ext.autodoc',
               'openstackdocstheme',
               'oslo_policy.sphinxext',
               'ext.support_matrix',
+              'sphinxcontrib.apidoc',
               ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../keystone'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'tests',
+    'test']
+apidoc_separate_modules = True
+
 config_generator_config_file = '../../config-generator/keystone.conf'
 sample_config_basename = '_static/keystone'
 

setup.cfg

@@ -47,13 +47,6 @@ tag_build =
 tag_date = 0
 tag_svn_revision = 0
 
-[build_sphinx]
-builder = html,man
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
 [compile_catalog]
 directory = keystone/locale
 domain = keystone
@@ -70,9 +63,6 @@ output_file = keystone/locale/keystone.pot
 copyright_holder = OpenStack Foundation
 msgid_bugs_address = https://bugs.launchpad.net/keystone
 
-[pbr]
-autodoc_tree_index_modules = True
-
 [entry_points]
 console_scripts =
     keystone-manage = keystone.cmd.manage:main

test-requirements.txt

@@ -23,13 +23,10 @@ lxml!=3.7.0,>=3.4.1 # BSD
 mock>=2.0.0 # BSD
 oslotest>=3.2.0 # Apache-2.0
 
-os-api-ref>=1.4.0 # Apache-2.0
 # test wsgi apps without starting an http server
 WebTest>=2.0.27 # MIT
-
 stestr>=1.0.0 # Apache-2.0
 testtools>=2.2.0 # MIT
-
 tempest>=17.1.0 # Apache-2.0
 
 # Functional tests.

tox.ini

@@ -18,11 +18,10 @@ whitelist_externals =
 passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY PBR_VERSION
 
 [testenv:api-ref]
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
-  rm -rf api-ref/build
+  bash -c "rm -rf api-ref/build"
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
-whitelist_externals =
-  rm
 
 [testenv:pep8]
 deps =
@@ -120,11 +119,13 @@ exclude=.venv,.git,.tox,build,dist,*lib/python*,*egg,tools,vendor,.update-venv,*
 max-complexity=24
 
 [testenv:docs]
-deps = -r{toxinidir}/doc/requirements.txt
+deps =
+  -r{toxinidir}/doc/requirements.txt
+  .[ldap,memcache,mongodb]
 commands=
     bash -c "rm -rf doc/build"
     bash -c "rm -rf doc/source/api"
-    python setup.py build_sphinx
+    sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
 deps = -r{toxinidir}/doc/requirements.txt