Fix docstring and avoid such errors

Docs in octavia where failing with:
Docstring of octavia.api.drivers.amphora_driver.v1.driver.AmphoraProviderDriver.create_vip_port:
10:Unexpected indentation.

The broken docstring is in octavia_lib/api/drivers/provider_base.py. Fix
that docstring and build apidocs - like octavia does - so that all
docstrings in this repo get tested.

For building apidocs, add the needed configuration to the sphinx files
and require the package.

Change-Id: Iad03f19083d9a5429dcfed3499d1c3e2d56cbb0f
Co-Authored-By: Jeremy Stanley <fungi@yuggoth.org>
Co-Authored-By: Adam Harwell <flux.adam@gmail.com>

doc/requirements.txt

@@ -1,5 +1,6 @@
 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,!=2.1.0,>=1.6.2;python_version>='3.4'  # BSD
 openstackdocstheme>=1.20.0  # Apache-2.0
+sphinxcontrib-apidoc>=0.2.1 # BSD
 # releasenotes
 reno>=2.5.0 # Apache-2.0

doc/source/conf.py

@@ -23,6 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     'openstackdocstheme',
+    'sphinxcontrib.apidoc'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -43,6 +44,13 @@ repository_name = 'openstack/octavia-lib'
 bug_project = 'openstack/octavia-lib'
 bug_tag = 'docs'
 
+apidoc_output_dir = 'reference/modules'
+apidoc_module_dir = '../../octavia_lib'
+apidoc_excluded_paths = [
+  'tests',
+  'db/migration'
+]
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 

doc/source/reference/index.rst

@@ -3,3 +3,8 @@ References
 ==========
 
 References of octavia-lib.
+
+.. toctree::
+   :hidden:
+
+   modules/modules

octavia_lib/api/drivers/provider_base.py

@@ -33,8 +33,8 @@ class ProviderDriver(object):
         a list of vip_dictionaries populated with data from the additional
         VIPs (which are guaranteed to be in the same Network).
         This might look like:
-        {'port_id': port_id, 'subnet_id': subnet_id_1, 'ip_address': ip1}, [
-            {'subnet_id': subnet_id_2, 'ip_address': ip2}, {...}, {...}]
+        {'port_id': port_id, 'subnet_id': subnet_id_1, 'ip_address': ip1},
+        [{'subnet_id': subnet_id_2, 'ip_address': ip2}, {...}, {...}]
         If the driver does not support port creation, the driver will raise
         a NotImplementedError.