help: support multiple examples

Should behave the same as before for modules that don't use the new
parameter to @sopel.module.example() to declare multiple help examples.

Updated admin.py module as a proof of concept. Going through other
modules and updating them with multiple examples is a separate project.

Output is still tweakable, but I'm happy enough without worrying about
splitting lines just yet.

sopel/loader.py

@@ -157,7 +157,7 @@ def clean_callable(func, config):
     help_prefix = config.core.help_prefix
     func._docs = {}
     doc = trim_docstring(func.__doc__)
-    example = None
+    examples = []
 
     func.unblockable = getattr(func, 'unblockable', False)
     func.priority = getattr(func, 'priority', 'medium')
@@ -185,13 +185,16 @@ def clean_callable(func, config):
             regexp = get_command_regexp(prefix, command)
             func.rule.append(regexp)
         if hasattr(func, 'example'):
-            example = func.example[0]["example"]
-            example = example.replace('$nickname', nick)
-            if example[0] != help_prefix and not example.startswith(nick):
-                example = example.replace(default_prefix, help_prefix, 1)
-        if doc or example:
+            # If no examples are flagged as user-facing, just show the first one like pre-6.6.0 did
+            examples = [rec["example"] for rec in func.example if rec["help"]] or [func.example[0]["example"]]
+            for i, example in enumerate(examples):
+                example = example.replace('$nickname', nick)
+                if example[0] != help_prefix and not example.startswith(nick):
+                    example = example.replace(default_prefix, help_prefix, 1)
+                examples[i] = example
+        if doc or examples:
             for command in func.commands:
-                func._docs[command] = (doc, example)
+                func._docs[command] = (doc, examples)
 
 
 def load_module(name, path, type_):

sopel/module.py

@@ -425,9 +425,12 @@ class example(object):
         ignore:
             List of outputs to ignore. Strings in this list are always
             interpreted as regular expressions.
+        user_help:
+            Whether this example should be displayed in user-facing help output
+            such as `.help command`.
     """
     def __init__(self, msg, result=None, privmsg=False, admin=False,
-                 owner=False, repeat=1, re=False, ignore=None):
+                 owner=False, repeat=1, re=False, ignore=None, user_help=False):
         # Wrap result into a list for get_example_test
         if isinstance(result, list):
             self.result = result
@@ -449,6 +452,8 @@ def __init__(self, msg, result=None, privmsg=False, admin=False,
         else:
             self.ignore = []
 
+        self.user_help = user_help
+
     def __call__(self, func):
         if not hasattr(func, "example"):
             func.example = []
@@ -474,6 +479,7 @@ def __call__(self, func):
             "result": self.result,
             "privmsg": self.privmsg,
             "admin": self.admin,
+            "help": self.user_help,
         }
         func.example.append(record)
         return func

sopel/modules/admin.py

@@ -41,7 +41,8 @@ def setup(bot):
 @sopel.module.require_admin
 @sopel.module.commands('join')
 @sopel.module.priority('low')
-@sopel.module.example('.join #example or .join #example key')
+@sopel.module.example('.join #example key', user_help=True)
+@sopel.module.example('.join #example', user_help=True)
 def join(bot, trigger):
     """Join the specified channel. This is an admin-only command."""
     channel, key = trigger.group(3), trigger.group(4)

sopel/modules/help.py

@@ -39,7 +39,7 @@ def help(bot, trigger):
         threshold = 3
 
         if name in bot.doc:
-            if len(bot.doc[name][0]) + (1 if bot.doc[name][1] else 0) > threshold:
+            if len(bot.doc[name][0]) + (1 if len(bot.doc[name][1]) else 0) > threshold:
                 if trigger.nick != trigger.sender:  # don't say that if asked in private
                     bot.reply('The documentation for this command is too long; I\'m sending it to you in a private message.')
                 msgfun = lambda l: bot.msg(trigger.nick, l)
@@ -49,7 +49,8 @@ def help(bot, trigger):
             for line in bot.doc[name][0]:
                 msgfun(line)
             if bot.doc[name][1]:
-                msgfun('e.g. ' + bot.doc[name][1])
+                examples = ', '.join(bot.doc[name][1][:-2] + [' or '.join(bot.doc[name][1][-2:])])
+                msgfun('e.g. ' + examples)
     else:
         # This'll probably catch most cases, without having to spend the time
         # actually creating the list first. Maybe worth storing the link and a