Updating for new sphinx docs jobs

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

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

Change-Id: I44f7ce2538de0ce76860a3a2b477751de322ab02

.gitignore

@@ -24,8 +24,10 @@ pip-log.txt
 
 # Unit test / coverage reports
 .coverage
+*.lock
 .tox
 nosetests.xml
+.secret_key_store
 .testrepository
 .venv
 node_modules
@@ -47,6 +49,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/contributor/modules
 
 # pbr generates these
 AUTHORS

doc/requirements.txt

@@ -0,0 +1,3 @@
+openstackdocstheme>=1.17.0  # Apache-2.0
+oslosphinx>=4.7.0 # Apache-2.0
+sphinx>=1.6.2 # BSD

doc/source/conf.py

@@ -12,18 +12,34 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import logging
 import os
 import sys
+from sphinx import apidoc
+
+import django
 
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('.'))
+
+logging.getLogger('openstack_dashboard.settings').setLevel(logging.ERROR)
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'openstack_dashboard.settings')
+
+django.setup()
+
 # -- 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 = [
+    'openstackdocstheme',
+    'oslosphinx',
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'sphinx.ext.coverage',
+    # 'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -57,6 +73,13 @@ pygments_style = 'sphinx'
 # html_theme_path = ["."]
 # html_theme = '_theme'
 # html_static_path = ['static']
+html_theme = 'openstackdocs'
+
+html_theme_options = {
+    'display_toc': False
+}
+
+html_static_path = []
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
@@ -72,7 +95,34 @@ latex_documents = [
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+# intersphinx_mapping = {'http://docs.python.org/': None}
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['octavia-dashboard.']
+
+
+# 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_dashboard')
+    # 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_dashboard/tests',
+        'octavia_dashboard/enabled',
+        'octavia_dashboard/locale',
+        'octavia_dashboard/static',
+        'octavia_dashboard/post_install.sh',
+        'octavia_dashboard/karma.conf.js'
+    ])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

doc/source/index.rst

@@ -14,11 +14,4 @@ Contents:
    readme
    installation
    contributing
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   reference

doc/source/reference.rst

@@ -0,0 +1,16 @@
+=========
+Reference
+=========
+
+Indices and search
+------------------
+
+.. toctree::
+   :hidden:
+
+   contributor/modules/modules
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

setup.cfg

@@ -31,5 +31,17 @@ all_files = 1
 upload-dir = doc/build/html
 
 [pbr]
-autodoc_index_modules = True
-warnerrors = True
+autodoc_tree_index_modules = False
+autodoc_tree_excludes =
+    setup.py
+    octavia_dashboard/tests
+    octavia_dashboard/enabled
+    octavia_dashboard/locale
+    octavia_dashboard/static
+    octavia_dashboard/post_install.sh
+    octavia_dashboard/karma.conf.js
+autodoc_index_modules = False
+autodoc_exclude_modules =
+    octavia_dashboard.tests.*
+    octavia_dashboard.enabled.*
+api_doc_dir = contributor/modules

test-requirements.txt

@@ -8,13 +8,10 @@ django-nose>=1.4.4 # BSD
 python-subunit>=1.0.0 # Apache-2.0/BSD
 nose-exclude>=0.3.0 # LGPL
 selenium>=2.50.1 # Apache-2.0
-sphinx>=1.6.2 # BSD
-oslosphinx>=4.7.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT
 reno>=2.5.0 # Apache-2.0
-openstackdocstheme>=1.17.0 # Apache-2.0
 # This also needs xvfb library installed on your OS
 xvfbwrapper>=0.1.3 #license: MIT

tox.ini

@@ -40,7 +40,15 @@ commands = nosetests octavia_dashboard/tests/integration_tests/tests {posargs}
 commands = python setup.py test --coverage --testr-args='{posargs}'
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+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
+  sphinx-build -W -b html doc/source doc/build/html
+
 
 [testenv:releasenotes]
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html