def __init__(self, obj, command_table, arg_table):
self.obj = obj
if command_table is None:
command_table = {}
self.command_table = command_table
if arg_table is None:
arg_table = {}
self.arg_table = arg_table
self._subcommand_table = {}
self._related_items = []
self.renderer = get_renderer()
self.doc = ReSTDocument(target='man')
def _write_ref_doc(self, command, output_dir, client_creator, parsed_args,
parsed_globals):
"""
Write the document for a single command.
"""
# Get the help command for the command to be documented.
if isinstance(command, HelpCommand):
help_command = command
else:
help_command = command.create_help_command()
# Derive the path of the command's documentation file, relative to the
# output directory.
# - Top-level commands, and any other commands that have subcommands,
# get index.rst files in directories of their own. Examples:
# - command foo => foo/index.rst (whether it has subcommands or not)
# - subcommand bar, which itself has subcommands, of command foo =>
# foo/bar/index.rst
# - Leaf subcommands get files named after themselves inside the
# directory of their parent command. Example:
# - subcommand baz of command foo => foo/baz.rst
# - Commands with no lineage (just cdp!) go to index.rst. If there are
# ever multiple lineage-less commands, this needs to be changed!
if hasattr(command, 'lineage'):
lineage = command.lineage
else:
lineage = []
if len(lineage) > 0:
ref_doc_partial_path = '/'.join(map(lambda c: c.name, lineage))
if (hasattr(command, '_get_command_table') and # has subcommands
command._get_command_table()) or \
(hasattr(command, 'subcommand_table') and # has subcommands
command.subcommand_table) or \
len(lineage) == 1: # is a top-level command (force this case)
ref_doc_path = '{}/index.rst'.format(ref_doc_partial_path)
else:
ref_doc_path = '{}.rst'.format(ref_doc_partial_path)
else:
ref_doc_path = 'index.rst' # the cdp command itself
print('- {}'.format(ref_doc_path))
# Run the help command to generate a ReST document suitable for HTML
# conversion.
help_command.doc = ReSTDocument(target='html')
help_command.renderer = NullRenderer()
help_command.include_man_fields = False
help_command(client_creator, [], parsed_globals)
# Create the directory for the document, if it doesn't already exist.
ref_doc_dir = os.path.join(output_dir, os.path.dirname(ref_doc_path))
if not os.path.exists(ref_doc_dir):
os.makedirs(ref_doc_dir)
# Write out the doc "value", which is the ReST string, to the file.
content = help_command.doc.getvalue()
with open(os.path.join(output_dir, ref_doc_path), 'w') as ref_doc:
ref_doc.write(str(content, encoding='utf-8'))
def create_help_command(self):
help_command = mock.Mock()
help_command.doc = ReSTDocument()
help_command.arg_table = {}
operation_model = mock.Mock()
operation_model.documentation = 'description'
operation_model.service_model.operation_names = []
help_command.obj = operation_model
return help_command
class HelpCommand(object):
GeneratorClass = None
def __init__(self, obj, command_table, arg_table, include_man_fields=True):
self.obj = obj
if command_table is None:
command_table = {}
self.command_table = command_table
if arg_table is None:
arg_table = {}
self.arg_table = arg_table
self.include_man_fields = include_man_fields
self._subcommand_table = {}
self._related_items = []
self.renderer = get_renderer()
self.doc = ReSTDocument(target='man')
@property
def command_lineage(self):
pass
@property
def name(self):
pass
@property
def subcommand_table(self):
return self._subcommand_table
@property
def related_items(self):
return self._related_items
def __call__(self, client_creator, args, parsed_globals):
if args:
subcommand_parser = ArgTableArgParser(
{}, command_table=self.subcommand_table)
parsed, remaining = subcommand_parser.parse_known_args(args)
if getattr(parsed, 'subcommand', None) is not None:
return self.subcommand_table[parsed.subcommand](remaining,
parsed_globals)
generate_doc(self.GeneratorClass(self), self)
self.renderer.render(self.doc.getvalue())
def test_documents_enum_values(self):
shape_map = {
'EnumArg': {
'type': 'string',
'enum': ['FOO', 'BAZ']
}
}
shape = StringShape('EnumArg',
shape_map['EnumArg'],
ShapeResolver(shape_map))
arg_table = {'arg-name': mock.Mock(argument_model=shape,
_UNDOCUMENTED=False)}
help_command = mock.Mock()
help_command.doc = ReSTDocument()
help_command.arg_table = arg_table
operation_model = mock.Mock()
operation_model.service_model.operation_names = []
help_command.obj = operation_model
operation_generator = OperationDocumentGenerator(help_command)
operation_generator.doc_option('arg-name', help_command)
rendered = help_command.doc.getvalue().decode('utf-8')
self.assertIn('Possible values', rendered)
self.assertIn('FOO', rendered)
self.assertIn('BAZ', rendered)