Fix some docs warnings and errors

These came out of "make html".

Change-Id: Iff009879de16bdad806b64e9f6beb64bb9cf6240

heat/api/cfn/v1/stacks.py

@@ -84,10 +84,10 @@ class StackController(object):
         Extract a dictionary of user input parameters for the stack
 
         In the AWS API parameters, each user parameter appears as two key-value
-        pairs with keys of the form below:
+        pairs with keys of the form below::
 
-        Parameters.member.1.ParameterKey
-        Parameters.member.1.ParameterValue
+          Parameters.member.1.ParameterKey
+          Parameters.member.1.ParameterValue
         """
         return api_utils.extract_param_pairs(params,
                                              prefix='Parameters',
@@ -274,8 +274,8 @@ class StackController(object):
 
     def create_or_update(self, req, action=None):
         """
-        Implements CreateStack and UpdateStack API actions
-        Create or update stack as defined in template file
+        Implements CreateStack and UpdateStack API actions.
+        Create or update stack as defined in template file.
         """
         def extract_args(params):
             """
@@ -365,8 +365,8 @@ class StackController(object):
 
     def get_template(self, req):
         """
-        Implements the GetTemplate API action
-        Get the template body for an existing stack
+        Implements the GetTemplate API action.
+        Get the template body for an existing stack.
         """
         self._enforce(req, 'GetTemplate')
 
@@ -399,8 +399,8 @@ class StackController(object):
 
     def validate_template(self, req):
         """
-        Implements the ValidateTemplate API action
-        Validates the specified template
+        Implements the ValidateTemplate API action.
+        Validates the specified template.
         """
         self._enforce(req, 'ValidateTemplate')
 
@@ -448,8 +448,8 @@ class StackController(object):
 
     def delete(self, req):
         """
-        Implements the DeleteStack API action
-        Deletes the specified stack
+        Implements the DeleteStack API action.
+        Deletes the specified stack.
         """
         self._enforce(req, 'DeleteStack')
 
@@ -468,8 +468,8 @@ class StackController(object):
 
     def events_list(self, req):
         """
-        Implements the DescribeStackEvents API action
-        Returns events related to a specified stack (or all stacks)
+        Implements the DescribeStackEvents API action.
+        Returns events related to a specified stack (or all stacks).
         """
         self._enforce(req, 'DescribeStackEvents')
 
@@ -519,15 +519,13 @@ class StackController(object):
 
     def describe_stack_resource(self, req):
         """
-        Implements the DescribeStackResource API action
+        Implements the DescribeStackResource API action.
         Return the details of the given resource belonging to the given stack.
         """
         self._enforce(req, 'DescribeStackResource')
 
         def format_resource_detail(r):
-            """
-            Reformat engine output into the AWS "StackResourceDetail" format
-            """
+            # Reformat engine output into the AWS "StackResourceDetail" format
             keymap = {
                 engine_api.RES_DESCRIPTION: 'Description',
                 engine_api.RES_UPDATED_TIME: 'LastUpdatedTimestamp',
@@ -568,9 +566,10 @@ class StackController(object):
         Implements the DescribeStackResources API action
         Return details of resources specified by the parameters.
 
-        `StackName`: returns all resources belonging to the stack
+        `StackName`: returns all resources belonging to the stack.
+
         `PhysicalResourceId`: returns all resources belonging to the stack this
-                              resource is associated with.
+        resource is associated with.
 
         Only one of the parameters may be specified.
 

heat/engine/hot.py

@@ -213,7 +213,7 @@ class HOTemplate(template.Template):
         """
         Resolve template string substitution via function str_replace
 
-        Resolves the str_replace function of the form
+        Resolves the str_replace function of the form::
 
           str_replace:
             template: <string template>

heat/engine/scheduler.py

@@ -207,7 +207,7 @@ def wrappertask(task):
 
     This is essentially a replacement for the Python 3-only "yield from"
     keyword (PEP 380), using the "yield" keyword that is supported in
-    Python 2. For example:
+    Python 2. For example::
 
         @wrappertask
         def parent_task(self):

heat/engine/service.py

@@ -242,7 +242,6 @@ class EngineService(service.Service):
         :param template: Template of stack you want to create.
         :param params: Stack Input Params
         :param files: Files referenced from the template
-                      (currently provider templates).
         :param args: Request parameters/args passed from API
         """
         logger.info('template is %s' % template)

heat/engine/template.py

@@ -316,12 +316,14 @@ class Template(collections.Mapping):
     @staticmethod
     def resolve_replace(s):
         """
-        Resolve constructs of the form.
-        {"Fn::Replace": [
-          {'$var1': 'foo', '%var2%': 'bar'},
-          '$var1 is %var2%'
-        ]}
-        This is implemented using python str.replace on each key
+        Resolve constructs of the form::
+
+          {"Fn::Replace": [
+            {'$var1': 'foo', '%var2%': 'bar'},
+            '$var1 is %var2%'
+          ]}
+
+        This is implemented using python str.replace on each key.
         """
         def handle_replace(args):
             if not isinstance(args, (list, tuple)):
@@ -367,10 +369,12 @@ class Template(collections.Mapping):
     @staticmethod
     def resolve_member_list_to_map(s):
         '''
-        Resolve constructs of the form
-        {'Fn::MemberListToMap': ['Name', 'Value', ['.member.0.Name=key',
-                                                   '.member.0.Value=door']]}
-        the first two arguments are the names of the key and value.
+        Resolve constructs of the form::
+
+          {'Fn::MemberListToMap': ['Name', 'Value', ['.member.0.Name=key',
+                                                     '.member.0.Value=door']]}
+
+        The first two arguments are the names of the key and value.
         '''
 
         def handle_member_list_to_map(args):

heat/rpc/client.py

@@ -26,7 +26,7 @@ import heat.openstack.common.rpc.proxy
 class EngineClient(heat.openstack.common.rpc.proxy.RpcProxy):
     '''Client side of the heat engine rpc API.
 
-    API version history:
+    API version history::
 
         1.0 - Initial version.
     '''
@@ -63,7 +63,7 @@ class EngineClient(heat.openstack.common.rpc.proxy.RpcProxy):
         Return detailed information about one or all stacks.
         :param ctxt: RPC context.
         :param stack_identity: Name of the stack you want to show, or None to
-                               show all
+        show all
         """
         return self.call(ctxt, self.make_msg('show_stack',
                                              stack_identity=stack_identity))