Updating for new sphinx docs jobs

There have been recent changes to how docs jobs are run under zuul [1].
This patch updates stable/pike to be able to run under the new zuul docs
jobs.

[1] https://review.openstack.org/#/c/508694/

(cherry picked from commit 967edebe0c4c1711aa6b566ed581bc33d51b611c)

Change-Id: I7ba3f7ea0b1e0733cec4e0cd3a05128c772e0238

doc/requirements.txt

@@ -10,6 +10,7 @@ sphinxcontrib-nwdiag
 sphinxcontrib-seqdiag
 graphviz
 openstackdocstheme>=1.11.0  # Apache-2.0
+os-api-ref>=1.0.0 # Apache-2.0
 
 # This needs to be installed after above modules
 pydotplus

doc/source/conf.py

@@ -11,9 +11,14 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import subprocess
 import os
+import sys
+
+from sphinx import apidoc
+
+sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('.'))
+
 from tools import create_flow_docs
 
 # Generate our flow diagrams
@@ -24,7 +29,6 @@ create_flow_docs.generate(
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('../../octavia'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -294,3 +298,25 @@ html_theme_options = {
 repository_name = 'openstack/octavia'
 bug_project = 'octavia'
 bug_tag = 'docs'
+
+# TODO(mordred) We should extract this into a sphinx plugin
+def run_apidoc(_):
+    cur_dir = os.path.abspath(os.path.dirname(__file__))
+    out_dir = os.path.join(cur_dir, 'contributor', 'modules')
+    module = os.path.join(cur_dir, '..', '..', 'octavia')
+    # Keep the order of arguments same as the sphinx-apidoc help, otherwise it
+    # would cause unexpected errors:
+    # sphinx-apidoc [options] -o <output_path> <module_path>
+    # [exclude_pattern, ...]
+    apidoc.main([
+        '--force',
+        '-o',
+        out_dir,
+        module,
+        'octavia/tests',
+        'octavia/db/migration'
+    ])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

doc/source/contributor/index.rst

@@ -81,7 +81,7 @@ Indices and Search
 .. toctree::
    :hidden:
 
-   modules/autoindex
+   modules/modules
 
 * :ref:`genindex`
 * :ref:`modindex`

setup.cfg

@@ -49,7 +49,7 @@ autodoc_tree_excludes =
     setup.py
     octavia/tests/
     octavia/db/migration/
-autodoc_index_modules = True
+autodoc_index_modules = False
 autodoc_exclude_modules =
     octavia.tests.*
     octavia.db.migration.*

test-requirements.txt

@@ -6,7 +6,6 @@ requests-mock>=1.1 # Apache-2.0
 coverage!=4.4,>=4.0 # Apache-2.0
 mock>=2.0 # BSD
 python-subunit>=0.0.18 # Apache-2.0/BSD
-os-api-ref>=1.0.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testtools>=1.4.0 # MIT
@@ -16,3 +15,5 @@ doc8 # Apache-2.0
 reno!=2.3.1,>=1.8.0 # Apache-2.0
 bandit>=1.1.0 # Apache-2.0
 tempest>=16.1.0 # Apache-2.0
+# Required for pep8 - doc8 tests
+sphinx>=1.6.2 # BSD

tox.ini

@@ -12,7 +12,6 @@ install_command =
 whitelist_externals = find
 deps = -r{toxinidir}/requirements.txt
        -r{toxinidir}/test-requirements.txt
-       -r{toxinidir}/doc-requirements.txt
 commands =
   {toxinidir}/tools/ostestr_compat_shim.sh {posargs}
 
@@ -71,9 +70,13 @@ whitelist_externals =
 
 [testenv:docs]
 whitelist_externals = rm
+deps =
+    -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+    -r{toxinidir}/requirements.txt
+    -r{toxinidir}/doc/requirements.txt
 commands =
-  rm -rf doc/build api-guide/build api-ref/build
-  python setup.py build_sphinx
+  rm -rf doc/build api-guide/build api-ref/build doc/source/contributor/modules
+  sphinx-build -W -b html doc/source doc/build/html
   sphinx-build -W -b html api-ref/source api-ref/build/html
 
 [testenv:venv]