fix restructuredtext formatting in docstrings that show up in the dev…

…eloper 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

doc/generate_autodoc_index.sh

@@ -15,11 +15,12 @@ do
   # and make sure to emit that many '=' under
   # it to avoid heading format errors
   # in Sphinx.
-  let heading_len=$(echo "$heading" | wc -c)
+  heading_len=$(echo "$heading" | wc -c)
   underline=$(head -c $heading_len < /dev/zero | tr '\0' '=')
   ( cat <<EOF
 ${heading}
 ${underline}
+
 .. automodule:: ${x}
   :members:
   :undoc-members:

doc/source/conf.py

@@ -92,7 +92,7 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.

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)

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

nova/api/openstack/compute/contrib/hosts.py

@@ -216,7 +216,9 @@ def show(self, req, id):
         :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}
         """

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"

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:

nova/auth/fakeldap.py

@@ -244,9 +244,9 @@ def delete_s(self, dn):
     def modify_s(self, dn, attrs):
         """Modify the object at dn using the attribute list.
 
-        Args:
-        dn -- a dn
-        attrs -- a list of tuples in the following form:
+        :param dn: a dn
+        :param attrs: a list of tuples in the following form::
+
             ([MOD_ADD | MOD_DELETE | MOD_REPACE], attribute, value)
 
         """