Add a Global Options section to help docs

awscli/bcdoc/docevents.py

@@ -23,6 +23,9 @@
     'doc-option': '.%s.%s',
     'doc-option-example': '.%s.%s',
     'doc-options-end': '.%s',
+    'doc-global-options-start': '.%s',
+    'doc-global-option': '.%s.%s',
+    'doc-global-options-end': '.%s',
     'doc-examples': '.%s',
     'doc-output': '.%s',
     'doc-subitems-start': '.%s',
@@ -57,6 +60,15 @@ def generate_events(session, help_command):
                 'doc-synopsis-option.%s.%s' % (help_command.event_class,
                                                arg_name),
                 arg_name=arg_name, help_command=help_command)
+    if help_command.global_arg_table:
+        for arg_name in help_command.global_arg_table:
+            if getattr(help_command.global_arg_table[arg_name],
+                       '_UNDOCUMENTED', False):
+                continue
+            session.emit(
+                'doc-synopsis-option.%s.%s' % (help_command.event_class,
+                                               arg_name),
+                arg_name=arg_name, help_command=help_command)
     session.emit('doc-synopsis-end.%s' % help_command.event_class,
                  help_command=help_command)
     session.emit('doc-options-start.%s' % help_command.event_class,
@@ -74,6 +86,18 @@ def generate_events(session, help_command):
                          arg_name=arg_name, help_command=help_command)
     session.emit('doc-options-end.%s' % help_command.event_class,
                  help_command=help_command)
+    if help_command.global_arg_table:
+        session.emit('doc-global-options-start.%s' % help_command.event_class,
+                    help_command=help_command)
+        for arg_name in help_command.global_arg_table:
+            if getattr(help_command.global_arg_table[arg_name],
+                    '_UNDOCUMENTED', False):
+                continue
+            session.emit('doc-global-option.%s.%s' % (help_command.event_class,
+                                                    arg_name),
+                        arg_name=arg_name, help_command=help_command)
+    session.emit('doc-global-options-end.%s' % help_command.event_class,
+                 help_command=help_command)
     session.emit('doc-subitems-start.%s' % help_command.event_class,
                  help_command=help_command)
     if help_command.command_table:

awscli/clidocs.py

@@ -124,7 +124,11 @@ def doc_synopsis_start(self, help_command, **kwargs):
 
     def doc_synopsis_option(self, arg_name, help_command, **kwargs):
         doc = help_command.doc
-        argument = help_command.arg_table[arg_name]
+        if arg_name in help_command.global_arg_table:
+            arg_table = help_command.global_arg_table
+        else:
+            arg_table = help_command.arg_table
+        argument = arg_table[arg_name]
         if argument.group_name in self._arg_groups:
             if argument.group_name in self._documented_arg_groups:
                 # This arg is already documented so we can move on.
@@ -178,6 +182,22 @@ def doc_option(self, arg_name, help_command, **kwargs):
             self._document_nested_structure(argument.argument_model, doc)
         doc.style.dedent()
         doc.style.new_paragraph()
+
+    def doc_global_options_start(self, help_command, **kwargs):
+        doc = help_command.doc
+        doc.style.h2('Global Options')
+
+    def doc_global_option(self, arg_name, help_command, **kwargs):
+        doc = help_command.doc
+        argument = help_command.global_arg_table[arg_name]
+        doc.writeln('``%s`` (%s)' % (argument.cli_name,
+                                     argument.cli_type_name))
+        doc.include_doc_string(argument.documentation)
+        if argument.choices:
+            doc.style.start_ul()
+            for choice in argument.choices:
+                doc.style.li(choice)
+            doc.style.end_ul()
 
     def doc_relateditems_start(self, help_command, **kwargs):
         if help_command.related_items:
@@ -283,21 +303,13 @@ def doc_synopsis_end(self, help_command, **kwargs):
         doc = help_command.doc
         doc.style.new_paragraph()
 
+    # A provider document's options are provided by
+    # the global option methods.
     def doc_options_start(self, help_command, **kwargs):
-        doc = help_command.doc
-        doc.style.h2('Options')
+        pass
 
     def doc_option(self, arg_name, help_command, **kwargs):
-        doc = help_command.doc
-        argument = help_command.arg_table[arg_name]
-        doc.writeln('``%s`` (%s)' % (argument.cli_name,
-                                     argument.cli_type_name))
-        doc.include_doc_string(argument.documentation)
-        if argument.choices:
-            doc.style.start_ul()
-            for choice in argument.choices:
-                doc.style.li(choice)
-            doc.style.end_ul()
+        pass
 
     def doc_subitems_start(self, help_command, **kwargs):
         doc = help_command.doc
@@ -335,6 +347,12 @@ def doc_option_example(self, arg_name, help_command, **kwargs):
     def doc_options_end(self, help_command, **kwargs):
         pass
 
+    def doc_global_option_start(self, help_command, **kwargs):
+        pass
+
+    def doc_global_option(self, help_command, **kwargs):
+        pass
+
     def doc_description(self, help_command, **kwargs):
         doc = help_command.doc
         service_model = help_command.obj

awscli/clidriver.py

@@ -139,6 +139,7 @@ def _build_builtin_commands(self, session):
         for service_name in services:
             commands[service_name] = ServiceCommand(cli_name=service_name,
                                                     session=self.session,
+                                                    global_arg_table=self._get_argument_table(),
                                                     service_name=service_name)
         return commands
 
@@ -293,7 +294,8 @@ class ServiceCommand(CLICommand):
 
     """
 
-    def __init__(self, cli_name, session, service_name=None):
+    def __init__(self, cli_name, session,
+                 global_arg_table={}, service_name=None):
         # The cli_name is the name the user types, the name we show
         # in doc, etc.
         # The service_name is the name we used internally with botocore.
@@ -306,6 +308,7 @@ def __init__(self, cli_name, session, service_name=None):
         # botocore expects.
         self._name = cli_name
         self.session = session
+        self._global_arg_table = global_arg_table
         self._command_table = None
         if service_name is None:
             # Then default to using the cli name.
@@ -323,6 +326,10 @@ def name(self):
     def name(self, value):
         self._name = value
 
+    @property
+    def global_arg_table(self):
+        return self._global_arg_table
+
     @property
     def service_model(self):
         return self._get_service_model()
@@ -372,6 +379,7 @@ def _create_command_table(self):
                 session=self.session,
                 operation_model=operation_model,
                 operation_caller=CLIOperationCaller(self.session),
+                global_arg_table=self.global_arg_table,
             )
         self.session.emit('building-command-table.%s' % self._name,
                           command_table=command_table,
@@ -418,7 +426,7 @@ class ServiceOperation(object):
     DEFAULT_ARG_CLASS = CLIArgument
 
     def __init__(self, name, parent_name, operation_caller,
-                 operation_model, session):
+                 operation_model, session, global_arg_table={}):
         """
 
         :type name: str
@@ -440,6 +448,7 @@ def __init__(self, name, parent_name, operation_caller,
 
         """
         self._arg_table = None
+        self._global_arg_table = global_arg_table
         self._name = name
         # These is used so we can figure out what the proper event
         # name should be <parent name>.<name>.
@@ -477,6 +486,10 @@ def arg_table(self):
         if self._arg_table is None:
             self._arg_table = self._create_argument_table()
         return self._arg_table
+
+    @property
+    def global_arg_table(self):
+        return self._global_arg_table
 
     def __call__(self, args, parsed_globals):
         # Once we know we're trying to call a particular operation
@@ -537,6 +550,7 @@ def create_help_command(self):
             self._session,
             operation_model=self._operation_model,
             arg_table=self.arg_table,
+            global_arg_table=self.global_arg_table,
             name=self._name, event_class='.'.join(self.lineage_names))
 
     def _add_help(self, parser):

awscli/help.py

@@ -206,7 +206,8 @@ class HelpCommand(object):
     EventHandler class used by this HelpCommand.
     """
 
-    def __init__(self, session, obj, command_table, arg_table):
+    def __init__(self, session, obj, command_table, arg_table,
+                 global_arg_table={}):
         self.session = session
         self.obj = obj
         if command_table is None:
@@ -215,6 +216,7 @@ def __init__(self, session, obj, command_table, arg_table):
         if arg_table is None:
             arg_table = {}
         self.arg_table = arg_table
+        self.global_arg_table = global_arg_table
         self._subcommand_table = {}
         self._related_items = []
         self.renderer = get_renderer()
@@ -284,7 +286,7 @@ class ProviderHelpCommand(HelpCommand):
     def __init__(self, session, command_table, arg_table,
                  description, synopsis, usage):
         HelpCommand.__init__(self, session, None,
-                             command_table, arg_table)
+                             command_table, arg_table, arg_table)
         self.description = description
         self.synopsis = synopsis
         self.help_usage = usage
@@ -336,7 +338,7 @@ class ServiceHelpCommand(HelpCommand):
     def __init__(self, session, obj, command_table, arg_table, name,
                  event_class):
         super(ServiceHelpCommand, self).__init__(session, obj, command_table,
-                                                 arg_table)
+                                                 arg_table, {})
         self._name = name
         self._event_class = event_class
 
@@ -358,9 +360,10 @@ class OperationHelpCommand(HelpCommand):
     """
     EventHandlerClass = OperationDocumentEventHandler
 
-    def __init__(self, session, operation_model, arg_table, name,
-                 event_class):
-        HelpCommand.__init__(self, session, operation_model, None, arg_table)
+    def __init__(self, session, operation_model, arg_table,
+                 global_arg_table, name, event_class):
+        HelpCommand.__init__(self, session, operation_model,
+                             None, arg_table, global_arg_table)
         self.param_shorthand = ParamShorthandParser()
         self._name = name
         self._event_class = event_class
@@ -378,7 +381,7 @@ class TopicListerCommand(HelpCommand):
     EventHandlerClass = TopicListerDocumentEventHandler
 
     def __init__(self, session):
-        super(TopicListerCommand, self).__init__(session, None, {}, {})
+        super(TopicListerCommand, self).__init__(session, None, {}, {}, {})
 
     @property
     def event_class(self):
@@ -393,7 +396,7 @@ class TopicHelpCommand(HelpCommand):
     EventHandlerClass = TopicDocumentEventHandler
 
     def __init__(self, session, topic_name):
-        super(TopicHelpCommand, self).__init__(session, None, {}, {})
+        super(TopicHelpCommand, self).__init__(session, None, {}, {}, {})
         self._topic_name = topic_name
 
     @property

tests/unit/customizations/test_commands.py

@@ -121,8 +121,8 @@ def test_expected_events_are_emitted_in_order(self):
         driver.main('s3 foo'.split())
 
         self.assert_events_fired_in_order([
-            'building-command-table.main',
             'building-top-level-params',
+            'building-command-table.main',
             'top-level-args-parsed',
             'session-initialized',
             'building-command-table.s3',

tests/unit/customizations/test_paginate.py

@@ -103,7 +103,8 @@ def test_injects_pagination_help_text(self):
         with mock.patch('awscli.customizations.paginate.get_paginator_config',
                    return_value={'result_key': 'abc'}):
             help_command = OperationHelpCommand(
-                mock.Mock(), mock.Mock(), mock.Mock(), 'foo', OperationDocumentEventHandler)
+                mock.Mock(), mock.Mock(), mock.Mock(), mock.Mock(),
+                'foo', OperationDocumentEventHandler)
             help_command.obj = mock.Mock(OperationModel)
             help_command.obj.name = 'foo'
             paginate.add_paging_description(help_command)
@@ -116,7 +117,8 @@ def test_shows_result_keys_when_array(self):
         with mock.patch('awscli.customizations.paginate.get_paginator_config',
                    return_value={'result_key': ['abc', '123']}):
             help_command = OperationHelpCommand(
-                mock.Mock(), mock.Mock(), mock.Mock(), 'foo', OperationDocumentEventHandler)
+                mock.Mock(), mock.Mock(), mock.Mock(), mock.Mock(),
+                'foo', OperationDocumentEventHandler)
             help_command.obj = mock.Mock(OperationModel)
             help_command.obj.name = 'foo'
             paginate.add_paging_description(help_command)
@@ -127,7 +129,8 @@ def test_does_not_show_result_key_if_not_present(self):
         with mock.patch('awscli.customizations.paginate.get_paginator_config',
                    return_value={'limit_key': 'aaa'}):
             help_command = OperationHelpCommand(
-                mock.Mock(), mock.Mock(), mock.Mock(), 'foo', OperationDocumentEventHandler)
+                mock.Mock(), mock.Mock(), mock.Mock(), mock.Mock(),
+                'foo', OperationDocumentEventHandler)
             help_command.obj = mock.Mock(OperationModel)
             help_command.obj.name = 'foo'
             paginate.add_paging_description(help_command)
@@ -140,7 +143,8 @@ def test_does_not_inject_when_no_pagination(self):
         with mock.patch('awscli.customizations.paginate.get_paginator_config',
                    return_value=None):
             help_command = OperationHelpCommand(
-                mock.Mock(), mock.Mock(), mock.Mock(), 'foo', OperationDocumentEventHandler)
+                mock.Mock(), mock.Mock(), mock.Mock(), mock.Mock(),
+                'foo', OperationDocumentEventHandler)
             help_command.obj = mock.Mock(OperationModel)
             help_command.obj.name = 'foo'
             paginate.add_paging_description(help_command)

tests/unit/test_clidriver.py

@@ -368,8 +368,8 @@ def test_expected_events_are_emitted_in_order(self):
         driver.main('s3 list-objects --bucket foo'.split())
         self.assert_events_fired_in_order([
             # Events fired while parser is being created.
-            'building-command-table.main',
             'building-top-level-params',
+            'building-command-table.main',
             'top-level-args-parsed',
             'session-initialized',
             'building-command-table.s3',
@@ -398,8 +398,8 @@ def test_create_help_command(self):
         command.create_help_command()
         self.assert_events_fired_in_order([
             # Events fired while parser is being created.
-            'building-command-table.main',
             'building-top-level-params',
+            'building-command-table.main',
             'building-command-table.s3',
         ])