cli: Allow adding a Notes section between Options and Commands

This is useful to document the interaction between options

swh/core/cli/__init__.py

@@ -3,8 +3,9 @@
 # License: GNU General Public License version 3, or any later version
 # See top-level LICENSE file for more information
 
-import click
 import logging
+
+import click
 import pkg_resources
 
 LOG_LEVEL_NAMES = ['NOTSET', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
@@ -15,7 +16,12 @@ logger = logging.getLogger(__name__)
 
 
 class AliasedGroup(click.Group):
-    'A simple Group that supports command aliases'
+    '''A simple Group that supports command aliases, as well as notes related to
+    options'''
+
+    def __init__(self, name=None, commands=None, **attrs):
+        self.option_notes = attrs.pop('option_notes', None)
+        super().__init__(name, commands, **attrs)
 
     @property
     def aliases(self):
@@ -31,6 +37,13 @@ class AliasedGroup(click.Group):
             name = name.name
         self.aliases[alias] = name
 
+    def format_options(self, ctx, formatter):
+        click.Command.format_options(self, ctx, formatter)
+        if self.option_notes:
+            with formatter.section('Notes'):
+                formatter.write_text(self.option_notes)
+        self.format_commands(ctx, formatter)
+
 
 @click.group(context_settings=CONTEXT_SETTINGS, cls=AliasedGroup)
 @click.option('--log-level', '-l', default='INFO',