def doc_option_example(self, arg_name, help_command, **kwargs): doc = help_command.doc cli_argument = help_command.arg_table[arg_name] if cli_argument.group_name in self._arg_groups: if cli_argument.group_name in self._documented_arg_groups: # Args with group_names (boolean args) don't # need to generate example syntax. return argument_model = cli_argument.argument_model docgen = ParamShorthandDocGen() if docgen.supports_shorthand(cli_argument): # TODO: bcdoc should not know about shorthand syntax. This # should be pulled out into a separate handler in the # awscli.customizations package. example_shorthand_syntax = docgen.generate_shorthand_example(cli_argument) if example_shorthand_syntax is None: # If the shorthand syntax returns a value of None, # this indicates to us that there is no example # needed for this param so we can immediately # return. return doc.style.new_paragraph() doc.write("Shorthand Syntax") doc.style.start_codeblock() for example_line in example_shorthand_syntax.splitlines(): doc.writeln(example_line) doc.style.end_codeblock() if ( argument_model is not None and argument_model.type_name == "list" and argument_model.member.type_name in SCALAR_TYPES ): # A list of scalars is special. While you *can* use # JSON ( ["foo", "bar", "baz"] ), you can also just # use the argparse behavior of space separated lists. # "foo" "bar" "baz". In fact we don't even want to # document the JSON syntax in this case. member = argument_model.member doc.style.new_paragraph() doc.write("Syntax") doc.style.start_codeblock() example_type = self._json_example_value_name(member, include_enum_values=False) doc.write("%s %s ..." % (example_type, example_type)) if isinstance(member, StringShape) and member.enum: # If we have enum values, we can tell the user # exactly what valid values they can provide. self._write_valid_enums(doc, member.enum) doc.style.end_codeblock() doc.style.new_paragraph() elif cli_argument.cli_type_name not in SCALAR_TYPES: doc.style.new_paragraph() doc.write("JSON Syntax") doc.style.start_codeblock() self._json_example(doc, argument_model, stack=[]) doc.style.end_codeblock() doc.style.new_paragraph()
def doc_option_example(self, arg_name, help_command, event_name, **kwargs): service_id, operation_name = \ find_service_and_method_in_event_name(event_name) doc = help_command.doc cli_argument = help_command.arg_table[arg_name] if cli_argument.group_name in self._arg_groups: if cli_argument.group_name in self._documented_arg_groups: # Args with group_names (boolean args) don't # need to generate example syntax. return argument_model = cli_argument.argument_model docgen = ParamShorthandDocGen() if docgen.supports_shorthand(cli_argument.argument_model): example_shorthand_syntax = docgen.generate_shorthand_example( cli_argument, service_id, operation_name) if example_shorthand_syntax is None: # If the shorthand syntax returns a value of None, # this indicates to us that there is no example # needed for this param so we can immediately # return. return if example_shorthand_syntax: doc.style.new_paragraph() doc.write('Shorthand Syntax') doc.style.start_codeblock() for example_line in example_shorthand_syntax.splitlines(): doc.writeln(example_line) doc.style.end_codeblock() if argument_model is not None and argument_model.type_name == 'list' and \ argument_model.member.type_name in SCALAR_TYPES: # A list of scalars is special. While you *can* use # JSON ( ["foo", "bar", "baz"] ), you can also just # use the argparse behavior of space separated lists. # "foo" "bar" "baz". In fact we don't even want to # document the JSON syntax in this case. member = argument_model.member doc.style.new_paragraph() doc.write('Syntax') doc.style.start_codeblock() example_type = self._json_example_value_name( member, include_enum_values=False) doc.write('%s %s ...' % (example_type, example_type)) if isinstance(member, StringShape) and member.enum: # If we have enum values, we can tell the user # exactly what valid values they can provide. self._write_valid_enums(doc, member.enum) doc.style.end_codeblock() doc.style.new_paragraph() elif cli_argument.cli_type_name not in SCALAR_TYPES: doc.style.new_paragraph() doc.write('JSON Syntax') doc.style.start_codeblock() self._json_example(doc, argument_model, stack=[]) doc.style.end_codeblock() doc.style.new_paragraph()
def doc_option_example(self, arg_name, help_command, **kwargs): doc = help_command.doc cli_argument = help_command.arg_table[arg_name] if cli_argument.group_name in self._arg_groups: if cli_argument.group_name in self._documented_arg_groups: # Args with group_names (boolean args) don't # need to generate example syntax. return argument_model = cli_argument.argument_model docgen = ParamShorthandDocGen() if docgen.supports_shorthand(cli_argument): # TODO: bcdoc should not know about shorthand syntax. This # should be pulled out into a separate handler in the # awscli.customizations package. example_shorthand_syntax = docgen.generate_shorthand_example( cli_argument) if example_shorthand_syntax is None: # If the shorthand syntax returns a value of None, # this indicates to us that there is no example # needed for this param so we can immediately # return. return doc.style.new_paragraph() doc.write('Shorthand Syntax') doc.style.start_codeblock() for example_line in example_shorthand_syntax.splitlines(): doc.writeln(example_line) doc.style.end_codeblock() if argument_model is not None and argument_model.type_name == 'list' and \ argument_model.member.type_name in SCALAR_TYPES: # A list of scalars is special. While you *can* use # JSON ( ["foo", "bar", "baz"] ), you can also just # use the argparse behavior of space separated lists. # "foo" "bar" "baz". In fact we don't even want to # document the JSON syntax in this case. doc.style.new_paragraph() doc.write('Syntax') doc.style.start_codeblock() example_type = self._json_example_value_name( argument_model.member, include_enum_values=False) doc.write('%s %s ...' % (example_type, example_type)) if 'enum' in argument_model.member.metadata: # If we have enum values, we can tell the user # exactly what valid values they can provide. enum = argument_model.member.metadata['enum'] self._write_valid_enums(doc, enum) doc.style.end_codeblock() doc.style.new_paragraph() elif cli_argument.cli_type_name not in SCALAR_TYPES: doc.style.new_paragraph() doc.write('JSON Syntax') doc.style.start_codeblock() self._json_example(doc, argument_model, stack=[]) doc.style.end_codeblock() doc.style.new_paragraph()