From 05b8ca95fd8b3a63ff46e9b584237cf99b32ac69 Mon Sep 17 00:00:00 2001
From: Andreas Jaeger <aj@suse.com>
Date: Sat, 3 Aug 2019 17:22:56 +0200
Subject: [PATCH] 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 +
 doc/source/conf.py                       | 8 ++++++++
 doc/source/reference/index.rst           | 5 +++++
 octavia_lib/api/drivers/provider_base.py | 4 ++--
 4 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 93d4e90..799550c 100644
--- a/doc/requirements.txt
+++ b/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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9698dd1..7f4cb4b 100755
--- a/doc/source/conf.py
+++ b/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
 
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index f186e83..07a2451 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -3,3 +3,8 @@ References
 ==========
 
 References of octavia-lib.
+
+.. toctree::
+   :hidden:
+
+   modules/modules
diff --git a/octavia_lib/api/drivers/provider_base.py b/octavia_lib/api/drivers/provider_base.py
index 10bc2de..a8b2a57 100644
--- a/octavia_lib/api/drivers/provider_base.py
+++ b/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.