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()
def setUp(self):
super(TestDocGen, self).setUp()
self.simplify = ParamShorthand()
self.shorthand_documenter = ParamShorthandDocGen()
from six import BytesIO
from docutils.core import publish_string
import awscli.clidriver
from awscli.argprocess import ParamShorthandDocGen
try:
from botocore.docs.bcdoc import textwriter
except ImportError:
from awscli.bcdoc import textwriter
from awsshell import determine_doc_index_filename
from awsshell.utils import remove_html
from awsshell import docs
SHORTHAND_DOC = ParamShorthandDocGen()
def new_index():
return {'arguments': [], 'argument_metadata': {},
'commands': [], 'children': {}}
def index_command(index_dict, help_command):
arg_table = help_command.arg_table
for arg in arg_table:
arg_obj = arg_table[arg]
metadata = {
'required': arg_obj.required,
'type_name': arg_obj.cli_type_name,
'minidoc': '',
def setUp(self):
super(TestDocGen, self).setUp()
self.shorthand_documenter = ParamShorthandDocGen()
self.service_name = 'foo'
self.operation_name = 'bar'
