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 details information, please refer to:

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

Change-Id: I6fb87036fa0f16e138aff975374abf5fa51a3298

.gitignore

@@ -23,7 +23,7 @@ cover
 coverage.xml
 dist
 doc/build/
-doc/source/sourcecode
+doc/source/contributor/api/
 horizon.egg-info
 node_modules
 nosetests.xml

doc/requirements.txt

@@ -0,0 +1,16 @@
+# 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.
+# Order matters to the pip dependency resolver, so sorting this file
+# changes how packages are installed.  New dependencies should be
+# added in alphabetical order, however, some dependencies may need to
+# be installed in a specific order.
+#
+# Requirements for docs
+django-nose>=1.4.4 # BSD
+mock>=2.0.0 # BSD
+mox3>=0.20.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

doc/source/conf.py

@@ -14,16 +14,29 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('../..'))
+import django
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
+
+sys.path.insert(0, ROOT)
+
+# This is required for ReadTheDocs.org, but isn't a bad idea anyway.
+os.environ.setdefault('DJANGO_SETTINGS_MODULE',
+                      'senlin_dashboard.test.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 = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'openstackdocstheme',
-]
+# 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.todo',
+              'sphinx.ext.coverage',
+              'sphinx.ext.viewcode',
+              'sphinxcontrib.apidoc',
+              'openstackdocstheme',
+              ]
 
 # Autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
@@ -39,6 +52,10 @@ master_doc = 'index'
 project = u'senlin-dashboard'
 copyright = u'2015, OpenStack Foundation'
 
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['**/#*', '**~', '**/#*#']
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -49,6 +66,13 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# sphinxcontrib-apidoc
+apidoc_module_dir = '../../senlin_dashboard'
+apidoc_output_dir = 'contributor/api'
+apidoc_excluded_paths = [
+    'test',
+]
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages. Major themes that come with

doc/source/contributor/api.rst

@@ -0,0 +1,8 @@
+Source Code Reference
+---------------------
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   api/*

doc/source/contributor/index.rst

@@ -34,3 +34,4 @@ authentication.
 
 .. include:: develop.rst
 
+.. include:: api.rst

lower-constraints.txt

@@ -103,6 +103,7 @@ simplejson==3.13.2
 six==1.11.0
 snowballstemmer==1.2.1
 Sphinx==1.6.2
+sphinxcontrib-apidoc===0.2.0
 sphinxcontrib-websupport==1.0.1
 stevedore==1.28.0
 termcolor==1.1.0

requirements.txt

@@ -3,7 +3,8 @@
 # process, which may cause wedges in the gate later.
 
 pbr!=2.1.0,>=2.0.0 # Apache-2.0
-python-senlinclient>=1.1.0 # Apache-2.0
 PyYAML>=3.12 # MIT
 
+python-senlinclient>=1.1.0 # Apache-2.0
+
 horizon>=14.0.0.0b1 # Apache-2.0

setup.cfg

@@ -26,7 +26,3 @@ setup-hooks =
 packages =
     senlin_dashboard
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1

test-requirements.txt

@@ -8,15 +8,3 @@ coverage!=4.4,>=4.0 # Apache-2.0
 django-nose>=1.4.4 # BSD
 mock>=2.0.0 # BSD
 mox3>=0.20.0 # Apache-2.0
-nodeenv>=0.9.4 # BSD
-nose>=1.3.7 # LGPL
-nose-exclude>=0.3.0 # LGPL
-nosexcover>=1.0.10 # BSD
-openstack.nose-plugin>=0.7 # Apache-2.0
-nosehtmloutput>=0.0.3 # Apache-2.0
-selenium>=2.50.1 # Apache-2.0
-xvfbwrapper>=0.1.3 #license: MIT
-# Docs Requirements
-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

tox.ini

@@ -80,22 +80,17 @@ commands =
   {toxinidir}/tools/tox_helper.sh {envname} {basepython} post
 
 [testenv:docs]
-commands =
-  # Clean-up env and install horizon from git
-  {toxinidir}/tools/tox_helper.sh {envname} {basepython} pre
-  # Run test
-  python setup.py build_sphinx
-  # Clean-up env except log
-  {toxinidir}/tools/tox_helper.sh {envname} {basepython} post
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/doc/requirements.txt
+commands=
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
+deps =
+  {[testenv:docs]deps}
 commands =
-  # Clean-up env and install horizon from git
-  {toxinidir}/tools/tox_helper.sh {envname} {basepython} pre
-  # Run test
   sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
-  # Clean-up env except log
-  {toxinidir}/tools/tox_helper.sh {envname} {basepython} post
 
 [testenv:debug]
 whitelist_externals = oslo_debug_helper