Stop using pbr sphinx integration

Switch to sphinx-build directly and add sphinxcontrib-apidoc for
generated api docs.

Change-Id: I089a7695986892dcb47c5b5e79a6a227891a2347

doc/requirements.txt

@@ -1,4 +1,5 @@
 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
 sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0

doc/source/conf.py

@@ -8,7 +8,7 @@ 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']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinxcontrib.apidoc']
 # make openstackdocstheme optional to not increase the needed dependencies
 try:
     import openstackdocstheme
@@ -72,3 +72,11 @@ latex_documents = [
      '%s Documentation' % project,
      'OpenStack Foundation', 'manual'),
 ]
+
+# -- sphinxcontrib.apidoc configuration --------------------------------------
+
+apidoc_module_dir = '../../pbr'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'tests',
+]

doc/source/reference/index.rst

@@ -3,6 +3,5 @@
 ===================
 
 .. toctree::
-   :glob:
 
-   api/*
+   api/modules

doc/source/user/history.rst

@@ -1,5 +0,0 @@
-=================
- Release History
-=================
-
-.. include:: ../../../ChangeLog

doc/source/user/index.rst

@@ -9,4 +9,3 @@
    packagers
    semver
    compatibility
-   history

lower-constraints.txt

@@ -25,6 +25,7 @@ requests==2.14.2
 six==1.10.0
 snowballstemmer==1.2.1
 Sphinx==1.6.5
+sphinxcontrib-apidoc==0.2.0
 sphinxcontrib-websupport==1.0.1
 stestr==2.1.0
 testrepository==0.0.18

setup.cfg

@@ -32,13 +32,6 @@ classifier =
 packages =
     pbr
 
-[pbr]
-autodoc_tree_index_modules = True
-autodoc_tree_excludes =
-   setup.py
-   pbr/tests/
-api_doc_dir = reference/api
-
 [entry_points]
 distutils.setup_keywords =
     pbr = pbr.core:pbr
@@ -47,11 +40,5 @@ egg_info.writers =
 console_scripts =
     pbr = pbr.cmd.main:main
 
-[build_sphinx]
-all-files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
 [bdist_wheel]
 universal = 1

tox.ini

@@ -23,13 +23,17 @@ commands = flake8 {posargs}
 
 [testenv:docs]
 basepython = python3
+whitelist_externals = rm
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
+commands =
+  rm -rf doc/build doc/source/reference/api
+  sphinx-build -W -b html doc/source doc/build/html {posargs}
 
 [testenv:releasenotes]
 basepython = python3
+whitelist_externals = rm
 deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt