Don't duplicate enum params

awscli/clidocs.py

@@ -268,9 +268,11 @@ def doc_description(self, help_command, **kwargs):
         doc.style.h2('Description')
         doc.include_doc_string(operation.documentation)
 
-    def _json_example_value_name(self, param):
+    def _json_example_value_name(self, param, include_enum_values=True):
+        # If include_enum_values is True, then the valid enum values
+        # are included as the sample JSON value.
         if param.type == 'string':
-            if hasattr(param, 'enum'):
+            if hasattr(param, 'enum') and include_enum_values:
                 choices = param.enum
                 return '|'.join(['"%s"' % c for c in choices])
             else:
@@ -370,8 +372,13 @@ def doc_option_example(self, arg_name, help_command, **kwargs):
             doc.style.new_paragraph()
             doc.write('Syntax')
             doc.style.start_codeblock()
-            example_type = self._json_example_value_name(param.members)
+            example_type = self._json_example_value_name(
+                param.members, include_enum_values=False)
             doc.write('%s %s ...' % (example_type, example_type))
+            if hasattr(param.members, 'enum'):
+                # If we have enum values, we can tell the user
+                # exactly what valid values they can provide.
+                self._write_valid_enums(doc, param.members.enum)
             doc.style.end_codeblock()
             doc.style.new_paragraph()
         elif argument.cli_type_name not in SCALAR_TYPES:
@@ -382,6 +389,13 @@ def doc_option_example(self, arg_name, help_command, **kwargs):
             doc.style.end_codeblock()
             doc.style.new_paragraph()
 
+    def _write_valid_enums(self, doc, enum_values):
+        doc.style.new_paragraph()
+        doc.write("Where valid values are:\n")
+        for value in enum_values:
+            doc.write("    %s\n" % value)
+        doc.write("\n")
+
     def _doc_member(self, doc, member_name, member):
         docs = member.get('documentation', '')
         if member_name:

tests/unit/docs/test_help_output.py

@@ -272,3 +272,26 @@ def test_description_from_rst_file(self):
         self.assert_contains('metadata_service_timeout')
         self.assert_contains('metadata_service_num_attempts')
         self.assert_contains('aws_access_key_id')
+
+class TestEnumDocsArentDuplicated(BaseAWSHelpOutputTest):
+    def test_enum_docs_arent_duplicated(self):
+        # Test for: https://github.com/aws/aws-cli/issues/609
+        # What's happening is if you have a list param that has
+        # an enum, we document it as:
+        # a|b|c|d   a|b|c|d
+        # Except we show all of the possible enum params twice.
+        # Each enum param should only occur once.  The ideal documentation
+        # should be:
+        #
+        # string1 string2
+        #
+        # Where each value is one of:
+        #     value1
+        #     value2
+        self.driver.main(['cloudformation', 'list-stacks', 'help'])
+        # "CREATE_IN_PROGRESS" is a enum value, and should only
+        # appear once in the help output.
+        contents = self.renderer.rendered_contents
+        self.assertTrue(contents.count("CREATE_IN_PROGRESS") == 1,
+                        ("Enum param was only suppose to be appear once in "
+                         "rendered doc output."))