From b8e166bb37b2200dd72942e517999e18834e16a3 Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Tue, 10 Jul 2018 18:55:31 -0500
Subject: [PATCH] Replace autodoc with sphinxcontrib-apidoc

Fix local docs builds back to the new docs PTI.

http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Also clean up after the removal of osc_lib.session

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

diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..1afc73d
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,7 @@
+# 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.5 # BSD
+sphinxcontrib-apidoc>=0.2.0 # BSD
diff --git a/doc/source/conf.py b/doc/source/conf.py
index b9a7e22..8e5ce4a 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,11 +18,6 @@ import sys
 import openstackdocstheme
 import pbr.version
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# 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(os.path.join(os.path.dirname(__file__), '..', '..')))
-
 # NOTE(blk-u): Path for our Sphinx extension, remove when
 # https://launchpad.net/bugs/1260495 is fixed.
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
@@ -38,6 +33,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               'sphinx.ext.todo',
               'openstackdocstheme',
+              'sphinxcontrib.apidoc',
               ]
 
 # openstackdocstheme options
@@ -265,3 +261,11 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+# -- Options for sphinxcontrib.apidoc ----------------------------------------
+
+apidoc_module_dir = '../../osc_lib'
+apidoc_excluded_paths = [
+    'tests/*',
+]
+apidoc_output_dir = 'reference/api'
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 547ab12..2256aec 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -5,4 +5,4 @@
 .. toctree::
    :maxdepth: 2
 
-   api/autoindex
+   api/modules
diff --git a/setup.cfg b/setup.cfg
index 5b5ac59..aa1147f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -21,15 +21,3 @@ classifier =
 [files]
 packages =
     osc_lib
-
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-warning-is-error = 1
-
-[pbr]
-autodoc_index_modules = True
-api_doc_dir = reference/api
-autodoc_exclude_modules =
-  osc_lib.tests.*
\ No newline at end of file
diff --git a/tox.ini b/tox.ini
index f9db43e..8d2b70c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -47,7 +47,13 @@ commands = oslo_debug_helper -t osc_lib/tests {posargs}
 
 [testenv:docs]
 basepython = python3
-commands = python setup.py build_sphinx
+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 =
+    sphinx-apidoc -o doc/api osc_lib osc_lib/tests
+    sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
 
 [testenv:releasenotes]
 basepython = python3