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

For more detials information, please refer to:

http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

Change-Id: I4b1b023ff2c40f5b31429584fc1a77c0315ed2d9
Co-Authored-By: Stephen Finucane <stephenfin@redhat.com>

.gitignore

@@ -48,6 +48,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/reference/api
 
 # pbr generates these
 AUTHORS

doc/requirements.txt

@@ -0,0 +1,9 @@
+# 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.
+# this is required for the docs build jobs
+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
+fixtures>=3.0.0 # Apache-2.0/BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD

doc/source/conf.py

@@ -12,17 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
-import sys
-
-
-sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
 # 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',
     'openstackdocstheme',
     'oslo_config.sphinxext',
 ]
@@ -31,18 +27,6 @@ extensions = [
 repository_name = 'openstack/oslo.concurrency'
 bug_project = 'oslo.concurrency'
 bug_tag = ''
-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
-
-# A list of glob-style patterns that should be excluded when looking for source
-# files.
-exclude_patterns = []
-
-# The suffix of source filenames.
-source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
@@ -61,26 +45,18 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output --------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
+# -- Options for HTML output -------------------------------------------------
+
 html_theme = 'openstackdocs'
-# html_static_path = ['static']
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
+# -- sphinxcontrib.apidoc configuration --------------------------------------
+
+apidoc_module_dir = '../../'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'oslo_concurrency/tests',
+    'oslo_concurrency/_*',
+    'setup.py',
 ]
-
-# Example configuration for intersphinx: refer to the Python standard library.
-# intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/reference/index.rst

@@ -10,3 +10,4 @@
    opts
    processutils
    watchdog
+   api/modules

test-requirements.txt

@@ -9,11 +9,6 @@ futures>=3.0.0;python_version=='2.7' or python_version=='2.6' # BSD
 fixtures>=3.0.0 # Apache-2.0/BSD
 stestr>=2.0.0 # Apache-2.0
 
-# These are needed for docs generation
-openstackdocstheme>=1.18.1 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-reno>=2.5.0 # Apache-2.0
-
 eventlet!=0.18.3,!=0.20.1,>=0.18.2 # MIT
 
 # Bandit security code scanner

tox.ini

@@ -6,12 +6,12 @@ envlist = py35,py27,pep8
 install_command = pip install {opts} {packages}
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
- -r{toxinidir}/test-requirements.txt
- -r{toxinidir}/requirements.txt
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/requirements.txt
 # We want to support both vanilla stdlib and eventlet monkey patched
 commands =
-    lockutils-wrapper stestr run --slowest {posargs}
-    env TEST_EVENTLET=1 lockutils-wrapper stestr run --slowest {posargs}
+  lockutils-wrapper stestr run --slowest {posargs}
+  env TEST_EVENTLET=1 lockutils-wrapper stestr run --slowest {posargs}
 
 [testenv:py27]
 basepython = python2.7
@@ -32,19 +32,22 @@ commands = {posargs}
 [testenv:docs]
 basepython = python3
 whitelist_externals = rm
+deps =
+  {[testenv]deps}
+  -r{toxinidir}/doc/requirements.txt
 commands =
-    rm -fr doc/build
-    sphinx-build -W -b html doc/source doc/build/html {posargs}
+  rm -fr doc/build
+  sphinx-build -W -b html doc/source doc/build/html {posargs}
 
 [testenv:cover]
 basepython = python3
 setenv =
-    PYTHON=coverage run --source oslo_concurrency --parallel-mode
+  PYTHON=coverage run --source oslo_concurrency --parallel-mode
 commands =
-    stestr run {posargs}
-    coverage combine
-    coverage html -d cover
-    coverage xml -o cover/coverage.xml
+  stestr run {posargs}
+  coverage combine
+  coverage html -d cover
+  coverage xml -o cover/coverage.xml
 
 [flake8]
 show-source = True
@@ -57,6 +60,7 @@ import_exceptions =
 
 [testenv:releasenotes]
 basepython = python3
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:lower-constraints]