fix restructuredtext formatting in docstrings that show up in the developer guide

blueprint sphinx-doc-cleanup
bug 945160

- Correct parameter declarations, list formatting, cross-references, etc.
- We don't need "let" in generate_autodoc_index.sh since we aren't doing math.
- Change conf.py to not prefix class and function names with full namespace
  in generated output to save width on the screen.

Change-Id: I9adc8681951913fd291d03e7142146e9d46841df

5 files changed, 27 insertions, 25 deletions

diff --git a/nova/api/openstack/common.py b/nova/api/openstack/common.py
index d2a909409..3fefa6718 100644
--- a/nova/api/openstack/common.py
+++ b/nova/api/openstack/common.py
@@ -144,17 +144,16 @@ def _get_marker_param(request):
 
 
 def limited(items, request, max_limit=FLAGS.osapi_max_limit):
-    """
-    Return a slice of items according to requested offset and limit.
+    """Return a slice of items according to requested offset and limit.
 
-    @param items: A sliceable entity
-    @param request: `wsgi.Request` possibly containing 'offset' and 'limit'
+    :param items: A sliceable entity
+    :param request: ``wsgi.Request`` possibly containing 'offset' and 'limit'
                     GET variables. 'offset' is where to start in the list,
                     and 'limit' is the maximum number of items to return. If
                     'limit' is not specified, 0, or > max_limit, we default
                     to max_limit. Negative values for either offset or limit
                     will cause exc.HTTPBadRequest() exceptions to be raised.
-    @kwarg max_limit: The maximum number of items to return from 'items'
+    :kwarg max_limit: The maximum number of items to return from 'items'
     """
     try:
         offset = int(request.GET.get('offset', 0))
@@ -309,15 +308,15 @@ def get_nw_info_for_instance(context, instance):
 
 
 def get_networks_for_instance(context, instance):
-    """Returns a prepared nw_info list for passing into the view
-    builders
-
-    We end up with a data structure like:
-    {'public': {'ips': [{'addr': '10.0.0.1', 'version': 4},
-                        {'addr': '2001::1', 'version': 6}],
-                'floating_ips': [{'addr': '172.16.0.1', 'version': 4},
-                                 {'addr': '172.16.2.1', 'version': 4}]},
-     ...}
+    """Returns a prepared nw_info list for passing into the view builders
+
+    We end up with a data structure like::
+
+        {'public': {'ips': [{'addr': '10.0.0.1', 'version': 4},
+                            {'addr': '2001::1', 'version': 6}],
+                    'floating_ips': [{'addr': '172.16.0.1', 'version': 4},
+                                     {'addr': '172.16.2.1', 'version': 4}]},
+         ...}
     """
     nw_info = get_nw_info_for_instance(context, instance)
     return get_networks_for_instance_from_nw_info(nw_info)
diff --git a/nova/api/openstack/compute/contrib/flavorextradata.py b/nova/api/openstack/compute/contrib/flavorextradata.py
index f821a8ffb..92189fd51 100644
--- a/nova/api/openstack/compute/contrib/flavorextradata.py
+++ b/nova/api/openstack/compute/contrib/flavorextradata.py
@@ -16,11 +16,12 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""
-The Flavor extra data extension
+"""The Flavor extra data extension
+
 Openstack API version 1.1 lists "name", "ram", "disk", "vcpus" as flavor
 attributes.  This extension adds to that list:
-   OS-FLV-EXT-DATA:ephemeral
+
+- OS-FLV-EXT-DATA:ephemeral
 """
 
 from nova import exception
diff --git a/nova/api/openstack/compute/contrib/hosts.py b/nova/api/openstack/compute/contrib/hosts.py
index df19872d7..a24b186c4 100644
--- a/nova/api/openstack/compute/contrib/hosts.py
+++ b/nova/api/openstack/compute/contrib/hosts.py
@@ -216,7 +216,9 @@ class HostController(object):
         :param context: security context
         :param host: hostname
         :returns: expected to use HostShowTemplate.
-            ex. {'host': {'resource':D},..}
+            ex.::
+
+                {'host': {'resource':D},..}
                 D: {'host': 'hostname','project': 'admin',
                     'cpu': 1, 'memory_mb': 2048, 'disk_gb': 30}
         """
diff --git a/nova/api/openstack/compute/limits.py b/nova/api/openstack/compute/limits.py
index 3245d49d2..4d533d522 100644
--- a/nova/api/openstack/compute/limits.py
+++ b/nova/api/openstack/compute/limits.py
@@ -382,8 +382,8 @@ class WsgiLimiter(object):
     """
     Rate-limit checking from a WSGI application. Uses an in-memory `Limiter`.
 
-    To use:
-        POST /<username> with JSON data such as:
+    To use, POST ``/<username>`` with JSON data such as::
+
         {
             "verb" : GET,
             "path" : "/servers"
diff --git a/nova/api/validator.py b/nova/api/validator.py
index f3824075e..cc89fe1d9 100644
--- a/nova/api/validator.py
+++ b/nova/api/validator.py
@@ -114,10 +114,11 @@ def validate_user_data(user_data):
 def validate(args, validator):
     """Validate values of args against validators in validator.
 
-    args            Dict of values to be validated.
-    validator       A dict where the keys map to keys in args
-                    and the values are validators.
-                    Applies each validator to args[key]
+    :param args:      Dict of values to be validated.
+    :param validator: A dict where the keys map to keys in args
+                      and the values are validators.
+                      Applies each validator to ``args[key]``
+    :returns: True if validation succeeds. Otherwise False.
 
     A validator should be a callable which accepts 1 argument and which
     returns True if the argument passes validation. False otherwise.
@@ -126,7 +127,6 @@ def validate(args, validator):
 
     Only validates keys which show up in both args and validator.
 
-    returns True if validation succeeds. Otherwise False.
     """
 
     for key in validator: