From 3a182268b9e1b39396f6dc8fa9261eddb5c41254 Mon Sep 17 00:00:00 2001
From: Anusha Ramineni <anusha.ramineni@nectechnologies.in>
Date: Wed, 11 Apr 2018 12:12:07 +0530
Subject: [PATCH] Follow the new PTI for document build

- Follow new PTI for docs build
- Add sphinxcontrib.apidoc to replace pbr autodoc

REF:
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

Change-Id: I40ee87cd5c7ff982db2da4de679419fbb94e1f72
---
 doc/requirements.txt  |  8 ++++++++
 doc/source/conf.py    | 14 +++++++++++---
 doc/source/index.rst  |  2 +-
 setup.cfg             | 19 -------------------
 test-requirements.txt |  7 -------
 tox.ini               |  5 ++++-
 6 files changed, 24 insertions(+), 31 deletions(-)
 create mode 100644 doc/requirements.txt

diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000..05b623776
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,8 @@
+# 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.
+
+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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 3ec7e8877..6d98863ad 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,10 +22,8 @@ sys.path.insert(0, os.path.abspath('./'))
 # 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',
-    #'openstackdocstheme',
-    #'sphinx.ext.intersphinx',
+    'sphinxcontrib.apidoc',
     'oslo_config.sphinxext',
     'oslo_config.sphinxconfiggen',
 ]
@@ -44,6 +42,16 @@ bug_tag = ''
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../congress'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'datalog.Python2.*',
+    'datalog.Python3.*',
+    'db.migration.alembic_migrations.*',]
+
+apidoc_separate_modules = True
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e20ef5430..c94019e18 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,7 +19,7 @@ Welcome to Congress!
 .. toctree::
    :hidden:
 
-   api/autoindex
+   api/modules
 
 
 * :ref:`genindex`
diff --git a/setup.cfg b/setup.cfg
index 478168a31..6a32f494b 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -31,16 +31,6 @@ data_files =
 setup-hooks =
     pbr.hooks.setup_hook
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-     congress.db.migration.alembic_migrations.*
-     thirdparty.*
-     antlr3runtime.*
-     congress.datalog.Python2.*
-     congress.datalog.Python3.*
-warnerrors = True
-
 [entry_points]
 oslo.config.opts =
     congress = congress.opts:list_opts
@@ -81,15 +71,6 @@ congress.datasource.drivers =
     swift = congress.datasources.swift_driver:SwiftDriver
     vcenter = congress.datasources.vCenter_driver:VCenterDriver
 
-[build_sphinx]
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = congress/locale
 domain = congress
diff --git a/test-requirements.txt b/test-requirements.txt
index 09753a658..e51aabe83 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -13,10 +13,3 @@ python-subunit>=1.0.0 # Apache-2.0/BSD
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT
-
-# Doc requirements
-openstackdocstheme>=1.18.1 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-
-# release note requirements
-reno>=2.5.0 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index fb8789d54..4eb104027 100644
--- a/tox.ini
+++ b/tox.ini
@@ -65,10 +65,13 @@ commands = oslopolicy-sample-generator --config-file etc/congress-policy-generat
 
 [testenv:docs]
 setenv = PYTHONHASHSEED=0
+deps = -r{toxinidir}/doc/requirements.txt
+       -r{toxinidir}/requirements.txt
 commands = rm -rf doc/build doc/source/api
-           python setup.py build_sphinx
+           sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:bindep]