Fix doc reference builds

The api reference was broken some time around the stein release.

Moved conf options out of setup.cfg and into the doc conf.py, and added
an option to doc build to error on warnings so this doesn't happen
again without anyone noticing. The format is now similar to the
novaclient reference doc.

Change-Id: Ic9ed059521794acf1ac1a644096fdc10549fa91b

doc/requirements.txt

@@ -4,3 +4,4 @@
 sphinx>=2.0.0,!=2.1.0 # BSD
 reno>=3.1.0 # Apache-2.0
 openstackdocstheme>=2.2.1 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0 # BSD

doc/source/conf.py

@@ -6,7 +6,11 @@
 
 # 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.viewcode', 'openstackdocstheme']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.apidoc',
+    'openstackdocstheme']
 
 # openstackdocstheme options
 openstackdocs_repo_name = 'openstack/python-designateclient'
@@ -14,6 +18,15 @@ openstackdocs_bug_project = 'python-designateclient'
 openstackdocs_bug_tag = ''
 html_theme = 'openstackdocs'
 
+apidoc_module_dir = '../../designateclient'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [ 'tests/*', 'functionaltests/*' ]
+apidoc_separate_modules = True
+
+autodoc_exclude_modules = [
+  'designateclient.tests.*',
+  'designateclient.functionaltests.*']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/source/reference/index.rst

@@ -3,5 +3,6 @@
 ==================================
 
 .. toctree::
+   :maxdepth: 4
 
-   api/autoindex
+   api/modules

setup.cfg

@@ -117,10 +117,3 @@ input_file = designateclient/locale/designateclient.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = designateclient/locale/designateclient.pot
-
-[pbr]
-autodoc_index_modules = True
-api_doc_dir = reference/api
-autodoc_exclude_modules =
-  designateclient.tests.*
-  designateclient.functionaltests.*

tox.ini

@@ -34,7 +34,7 @@ deps =
        -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
        -r{toxinidir}/requirements.txt
        -r{toxinidir}/doc/requirements.txt
-commands = sphinx-build -b html doc/source doc/build/html
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:flake8]
 commands = flake8