Follow the new PTI for document build

For compliance with the Project Testing Interface as described in:
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

Co-Authored-By: Nguyen Hai <nguyentrihai93@gmail.com>
Change-Id: Ia0a27229f09467980ff4af014001febb017bb36d

doc/requirements.txt

@@ -7,6 +7,7 @@ doc8>=0.6.0 # Apache-2.0
 openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 
 # For autodoc builds
 mock>=2.0.0 # BSD

doc/source/conf.py

@@ -10,7 +10,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from __future__ import unicode_literals
 
 import os
 import sys
@@ -37,14 +36,23 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
 # 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.todo',
+extensions = ['sphinx.ext.todo',
               'sphinx.ext.coverage',
               'sphinx.ext.intersphinx',
               'openstackdocstheme',
-              'oslo_config.sphinxconfiggen'
+              'oslo_config.sphinxconfiggen',
+              'sphinxcontrib.apidoc',
              ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../keystonemiddleware'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'tests',
+    'test']
+apidoc_separate_modules = True
+
 config_generator_config_file = '../../config-generator/keystonemiddleware.conf'
 sample_config_basename = '_static/keystonemiddleware'
 

setup.cfg

@@ -40,19 +40,6 @@ paste.filter_factory =
     ec2_token = keystonemiddleware.ec2_token:filter_factory
     s3_token = keystonemiddleware.s3_token:filter_factory
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-warning-is-error = 1
-
-[pbr]
-autodoc_tree_index_modules = True
-autodoc_tree_excludes = setup.py
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = keystonemiddleware/locale
 domain = keystonemiddleware

test-requirements.txt

@@ -10,7 +10,6 @@ cryptography>=2.1 # BSD/Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 mock>=2.0.0 # BSD
 oslotest>=3.2.0 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
 requests-mock>=1.2.0 # Apache-2.0
 stevedore>=1.20.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD

tox.ini

@@ -54,7 +54,7 @@ exclude = .venv,.tox,dist,doc,*egg,build
 deps = -r{toxinidir}/doc/requirements.txt
 commands=
     doc8 doc/source
-    python setup.py build_sphinx
+    sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
 deps = -r{toxinidir}/doc/requirements.txt