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

@@ -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

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'

doc/source/reference/index.rst

@@ -5,4 +5,4 @@
 .. toctree::
    :maxdepth: 2
 
-   api/autoindex
+   api/modules

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.*

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