Fix python modules docs build

Currently the Python code documentation is not being published at all
which can be observed by visiting

https://docs.openstack.org/neutron-lib/latest/genindex.html

This used to work in the old versions, for example in 1.9.1:

https: //docs.openstack.org/neutron-lib/1.9.1/genindex.html

Docstring fixes in placement/utils.py:

When Sphinx generates documentation, it produces following warning:
"WARNING: Definition list ends without a blank line; unexpected unindent.""

This commit adds the missing lines, but also switches to :: so that
contents of the definitions are treated as raw text.

Change-Id: Ibb919c53d7e1bc2710e85ae86a0ed0d7620a900c

doc/requirements.txt

@@ -1,4 +1,5 @@
 sphinx>=2.0.0 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
 openstackdocstheme>=2.2.1 # Apache-2.0
 os-api-ref>=1.4.0 # Apache-2.0
 reno>=3.1.0 # Apache-2.0

doc/source/conf.py

@@ -39,7 +39,9 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.ifconfig',
               'sphinx.ext.graphviz',
               'sphinx.ext.todo',
-              'openstackdocstheme',]
+              'openstackdocstheme',
+              'sphinxcontrib.apidoc',
+              ]
 
 todo_include_todos = True
 
@@ -232,3 +234,15 @@ linkcheck_anchors_ignore = [
     r'q\,.*',
     r'\/c\/.*'
 ]
+
+apidoc_module_dir = '../../neutron_lib/'
+apidoc_output_dir = 'reference/modules/'
+apidoc_excluded_paths = [
+    'db/model_base.py',
+    'db/resource_extend.py',
+    'db/sqlalchemytypes.py',
+    'fixture.py',
+    'hacking/*',
+    'tests/*',
+]
+apidoc_separate_modules = True

doc/source/index.rst

@@ -51,3 +51,4 @@ Enjoy!
       :maxdepth: 1
 
       reference/index
+      Package Reference <reference/modules/modules>

neutron_lib/placement/utils.py

@@ -183,11 +183,16 @@ def _parse_rp_options(options, dict_keys):
 def parse_rp_bandwidths(bandwidths):
     """Parse and validate config option: resource_provider_bandwidths.
 
-    Input in the config:
+    Input in the config::
+
         resource_provider_bandwidths = eth0:10000:10000,eth1::10000,eth2::,eth3
-    Input here:
+
+    Input here::
+
         ['eth0:10000:10000', 'eth1::10000', 'eth2::', 'eth3']
-    Output:
+
+    Output::
+
         {
             'eth0': {'egress': 10000, 'ingress': 10000},
             'eth1': {'egress': None, 'ingress': 10000},
@@ -224,12 +229,17 @@ def _rp_pp_set_default_hypervisor(cfg, host):
 def parse_rp_pp_with_direction(pkt_rates, host):
     """Parse and validate: resource_provider_packet_processing_with_direction.
 
-    Input in the config:
+    Input in the config::
+
         resource_provider_packet_processing_with_direction =
             host0:10000:10000,host1::10000,host2::,host3,:0:0
-    Input here:
+
+    Input here::
+
         ['host0:10000:10000', 'host1::10000', 'host2::', 'host3', ':0:0']
-    Output:
+
+    Output::
+
         {
             'host0': {'egress': 10000, 'ingress': 10000},
             'host1': {'egress': None, 'ingress': 10000},
@@ -263,12 +273,17 @@ def parse_rp_pp_with_direction(pkt_rates, host):
 def parse_rp_pp_without_direction(pkt_rates, host):
     """Parse: resource_provider_packet_processing_without_direction.
 
-    Input in the config:
+    Input in the config::
+
         resource_provider_packet_processing_without_direction =
             host0:10000,host1:,host2,:0
-    Input here:
+
+    Input here::
+
         ['host0:10000', 'host1:', 'host2', ':0']
-    Output:
+
+    Output::
+
         {
             'host0': {'any': 10000},
             'host1': {'any': None},
@@ -301,14 +316,19 @@ def parse_rp_inventory_defaults(inventory_defaults):
 
     Cast the dict values to the proper numerical types.
 
-    Input in the config:
+    Input in the config::
+
         resource_provider_inventory_defaults = allocation_ratio:1.0,min_unit:1
-    Input here:
+
+    Input here::
+
         {
             'allocation_ratio': '1.0',
             'min_unit': '1',
         }
-    Output here:
+
+    Output here::
+
         {
             'allocation_ratio': 1.0,
             'min_unit': 1,