Add usage examples for all settings

modules/accept_invite.py

@@ -2,7 +2,7 @@ from src import ModuleManager, utils
 
 @utils.export("serverset", {"setting": "accept-invites",
     "help": "Set whether I accept invites on this server",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.invite")
     def on_invite(self, event):

modules/auto_mode.py

@@ -1,7 +1,8 @@
 from src import ModuleManager, utils
 
 @utils.export("channelset", {"setting": "automode",
-    "help": "Disable/Enable automode", "validate": utils.bool_or_none})
+    "help": "Disable/Enable automode", "validate": utils.bool_or_none,
+    "example": "on"})
 class Module(ModuleManager.BaseModule):
     _name = "AutoMode"
 

modules/birthday.py

@@ -31,7 +31,7 @@ def _apostrophe(nickname):
     return "%s's" % nickname
 
 @utils.export("set", {"setting": "birthday", "help": "Set your birthday",
-    "validate": _check})
+    "validate": _check, "example": "1995-09-15"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.command.birthday")
     def birthday(self, event):

modules/bot_channel.py

@@ -1,7 +1,7 @@
 from src import ModuleManager, utils
 
 @utils.export("serverset", {"setting": "bot-channel",
-    "help": "Set main channel"})
+    "help": "Set main channel", "example": "#bitbot"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.001")
     def do_join(self, event):

modules/channel_log/__init__.py

@@ -5,8 +5,8 @@ ROOT_DIRECTORY = os.path.dirname(os.path.realpath(__file__))
 LOGS_DIRECTORY = os.path.join(ROOT_DIRECTORY, "logs")
 
 @utils.export("channelset", {"setting": "log",
-    "help": "Enable/disable channel logging",
+    "help": "Enable/disable channel logging", "validate": utils.bool_or_none,
-    "validate": utils.bool_or_none})
+    "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _log_file(self, server_name, channel_name):
         return open(os.path.join(LOGS_DIRECTORY,

modules/channel_op.py

@@ -7,15 +7,17 @@ class InvalidTimeoutException(Exception):
 
 @utils.export("channelset", {"setting": "highlight-spam-threshold",
     "help": "Set the number of nicknames in a message that qualifies as spam",
-     "validate": utils.int_or_none})
+     "validate": utils.int_or_none, "example": "10"})
 @utils.export("channelset", {"setting": "highlight-spam-protection",
     "help": "Enable/Disable highlight spam protection",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "highlight-spam-ban",
     "help": "Enable/Disable banning highlight spammers "
-    "instead of just kicking", "validate": utils.bool_or_none})
+    "instead of just kicking", "validate": utils.bool_or_none,
+    "example": "on"})
 @utils.export("channelset", {"setting": "ban-format",
-    "help": "Set ban format ($n = nick, $u = username, $h = hostname)"})
+    "help": "Set ban format ($n = nick, $u = username, $h = hostname)",
+    "example": "*!$u@$h"})
 class Module(ModuleManager.BaseModule):
     _name = "ChanOp"
 

modules/check_mode.py

@@ -5,9 +5,11 @@ LOWHIGH = {
     "high": "o"
 }
 @utils.export("channelset", {"setting": "mode-low",
-    "help": "Set which channel mode is considered to be 'low' access"})
+    "help": "Set which channel mode is considered to be 'low' access",
+    "example": "v"})
 @utils.export("channelset", {"setting": "mode-high",
-    "help": "Set which channel mode is considered to be 'high' access"})
+    "help": "Set which channel mode is considered to be 'high' access",
+    "example": "o"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("preprocess.command")
     def preprocess_command(self, event):

modules/check_urls.py

@@ -8,13 +8,14 @@ RE_URL = re.compile(r"https?://\S+", re.I)
 
 @utils.export("channelset", {"setting": "check-urls",
     "help": "Enable/Disable automatically checking for malicious URLs",
-     "validate": utils.bool_or_none})
+     "validate": utils.bool_or_none, "example": "on"})
 @utils.export("serverset", {"setting": "check-urls",
     "help": "Enable/Disable automatically checking for malicious URLs",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "check-urls-kick",
     "help": "Enable/Disable automatically kicking users that "
-    "send malicious URLs", "validate": utils.bool_or_none})
+    "send malicious URLs", "validate": utils.bool_or_none,
+    "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.message.channel")
     def message(self, event):

modules/commands/__init__.py

@@ -14,24 +14,24 @@ def _command_method_validate(s):
         return s.upper()
 
 @utils.export("channelset", {"setting": "command-prefix",
-    "help": "Set the command prefix used in this channel"})
+    "help": "Set the command prefix used in this channel", "example": "!"})
 @utils.export("serverset", {"setting": "command-prefix",
-    "help": "Set the command prefix used on this server"})
+    "help": "Set the command prefix used on this server", "example": "!"})
 @utils.export("serverset", {"setting": "command-method",
     "help": "Set the method used to respond to commands",
-    "validate": _command_method_validate})
+    "validate": _command_method_validate, "example": "NOTICE"})
 @utils.export("channelset", {"setting": "command-method",
     "help": "Set the method used to respond to commands",
-    "validate": _command_method_validate})
+    "validate": _command_method_validate, "example": "NOTICE"})
 @utils.export("channelset", {"setting": "hide-prefix",
     "help": "Disable/enable hiding prefix in command reponses",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "commands",
     "help": "Disable/enable responding to commands in-channel",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "prefixed-commands",
     "help": "Disable/enable responding to prefixed commands in-channel",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def on_load(self):
         self.exports.add("is-ignored", self._is_ignored)

modules/ctcp.py

@@ -4,7 +4,7 @@ from src import IRCBot, ModuleManager, utils
 
 @utils.export("serverset", {"setting": "ctcp-responses",
     "help": "Set whether I respond to CTCPs on this server",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.ctcp.version.private")
     def ctcp_version(self, event):

modules/ducks.py

@@ -7,13 +7,14 @@ NO_DUCK = "There was no duck!"
 DEFAULT_MIN_MESSAGES = 100
 
 @utils.export("channelset", {"setting": "ducks-enabled",
-    "help": "Whether or not to spawn ducks", "validate": utils.bool_or_none})
+    "help": "Whether or not to spawn ducks", "validate": utils.bool_or_none,
+    "example": "on"})
 @utils.export("channelset", {"setting": "ducks-min-messages",
     "help": "Minimum messages between ducks spawning",
-    "validate": utils.int_or_none})
+    "validate": utils.int_or_none, "example": "50"})
 @utils.export("channelset", {"setting": "ducks-kick",
     "help": "Whether or not to kick someone talking to non-existent ducks",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("new.channel")
     def new_channel(self, event):

modules/github/__init__.py

@@ -93,18 +93,19 @@ CHECK_RUN_FAILURES = ["failure", "cancelled", "timed_out", "action_required"]
 
 @utils.export("channelset", {"setting": "github-hide-prefix",
     "help": "Hide/show command-like prefix on Github hook outputs",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "github-hide-organisation",
     "help": "Hide/show organisation in repository names",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "github-default-repo",
-    "help": "Set the default github repo for the current channel"})
+    "help": "Set the default github repo for the current channel",
+    "example": "jesopo/bitbot"})
 @utils.export("channelset", {"setting": "github-prevent-highlight",
     "help": "Enable/disable preventing highlights",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "auto-github",
     "help": "Enable/disable automatically getting github issue/PR info",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _parse_ref(self, channel, ref):
         repo, _, number = ref.rpartition("#")

modules/google.py

@@ -9,7 +9,7 @@ URL_GOOGLESUGGEST = "http://google.com/complete/search"
 
 @utils.export("channelset", {"setting": "google-safesearch",
     "help": "Turn safe search off/on",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.command.g", alias_of="google")
     @utils.hook("received.command.google")

modules/greeting.py

@@ -1,7 +1,8 @@
 from src import ModuleManager, utils
 
 @utils.export("channelset", {"setting": "greeting",
-    "help": "Set a greeting to send to users when they join"})
+    "help": "Set a greeting to send to users when they join",
+    "example": "welcome to the channel!"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.join")
     def join(self, event):

modules/imgur.py

@@ -16,7 +16,7 @@ NSFW_TEXT = "(NSFW)"
 
 @utils.export("channelset", {"setting": "auto-imgur",
     "help": "Disable/Enable automatically getting info from Imgur URLs",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _prefix(self, data):
         text = "%s: " % data["id"]

modules/karma.py

@@ -7,10 +7,10 @@ KARMA_DELAY_SECONDS = 3
 
 @utils.export("channelset", {"setting": "karma-verbose",
     "help": "Enable/disable automatically responding to karma changes",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("serverset", {"setting": "karma-nickname-only",
     "help": "Enable/disable karma being for nicknames only",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _karma_str(self, karma):
         karma_str = str(karma)

modules/lastfm.py

@@ -5,7 +5,8 @@ from src import ModuleManager, utils
 
 URL_SCROBBLER = "http://ws.audioscrobbler.com/2.0/"
 
-@utils.export("set", {"setting": "lastfm", "help": "Set last.fm username"})
+@utils.export("set", {"setting": "lastfm", "help": "Set last.fm username",
+    "example": "jesopo"})
 class Module(ModuleManager.BaseModule):
     _name = "last.fm"
 

modules/nickserv.py

@@ -2,7 +2,8 @@ import base64
 from src import EventManager, ModuleManager, utils
 
 @utils.export("serverset", {"setting": "nickserv-password",
-    "help": "Set the nickserv password for this server"})
+    "help": "Set the nickserv password for this server",
+    "example": "hunter2"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.001", priority=EventManager.PRIORITY_URGENT)
     def on_connect(self, event):

modules/permissions/__init__.py

@@ -6,7 +6,8 @@ REQUIRES_IDENTIFY = ("You need to be identified to use that command "
  "(/msg %s register | /msg %s identify)")
 
 @utils.export("serverset", {"setting": "identity-mechanism",
-    "help": "Set the identity mechanism for this server"})
+    "help": "Set the identity mechanism for this server",
+    "example": "ircv3-account"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("new.user")
     def new_user(self, event):

modules/print_activity.py

@@ -2,7 +2,8 @@ import datetime
 from src import EventManager, ModuleManager, utils
 
 @utils.export("botset", {"setting": "print-motd",
-    "help": "Set whether I print /motd", "validate": utils.bool_or_none})
+    "help": "Set whether I print /motd", "validate": utils.bool_or_none,
+    "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _print(self, event):
         self.bot.log.info("%s%s | %s", [

modules/pronouns.py

@@ -1,6 +1,7 @@
 from src import ModuleManager, utils
 
-@utils.export("set", {"setting": "pronouns", "help": "Set your pronouns"})
+@utils.export("set", {"setting": "pronouns", "help": "Set your pronouns",
+    "example": "she/her"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.command.pronouns")
     def pronouns(self, event):

modules/rest_api.py

@@ -109,10 +109,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
 
 @utils.export("botset", {"setting": "rest-api",
     "help": "Enable/disable REST API",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("botset", {"setting": "rest-api-minify",
     "help": "Enable/disable REST API minifying",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def on_load(self):
         global _bot

modules/sasl/__init__.py

@@ -17,7 +17,7 @@ def _validate(self, s):
 
 @utils.export("serverset", {"setting": "sasl",
     "help": "Set the sasl username/password for this server",
-    "validate": _validate})
+    "validate": _validate, "example": "PLAIN BitBot:hunder2"})
 class Module(ModuleManager.BaseModule):
     def _best_userpass_mechanism(self, mechanisms):
         for potential_mechanism in USERPASS_MECHANISMS:

modules/sed.py

@@ -6,10 +6,10 @@ REGEX_SED = re.compile("^s/")
 
 @utils.export("channelset", {"setting": "sed",
     "help": "Disable/Enable sed in a channel",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "sed-sender-only",
     "help": "Disable/Enable sed only looking at the messages sent by the user",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _closest_setting(self, event, setting, default):
         return event["target"].get_setting(setting,

modules/strip_color.py

@@ -2,10 +2,10 @@ from src import ModuleManager, utils
 
 @utils.export("serverset", {"setting": "strip-color",
     "help": "Set whether I strip colors from my messages on this server",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "strip-color",
     "help": "Set whether I strip colors from my messages on in this channel",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("preprocess.send.privmsg")
     @utils.hook("preprocess.send.notice")

modules/title.py

@@ -3,14 +3,14 @@ from src import EventManager, ModuleManager, utils
 
 @utils.export("channelset", {"setting": "auto-title",
     "help": "Disable/Enable automatically getting info titles from URLs",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "title-shorten",
     "help": "Enable/disable shortening URLs when getting their title",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "auto-title-first",
     "help": ("Enable/disable showing who first posted a URL that was "
         "auto-titled"),
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "exaple": "on"})
 class Module(ModuleManager.BaseModule):
     def _url_hash(self, url):
         return "sha256:%s" % hashlib.sha256(url.lower().encode("utf8")

modules/trakt.py

@@ -5,7 +5,8 @@ from src import ModuleManager, utils
 URL_TRAKT = "https://api-v2launch.trakt.tv/users/%s/watching"
 URL_TRAKTSLUG = "https://trakt.tv/%s/%s"
 
-@utils.export("set", {"setting": "trakt", "help": "Set username on trakt.tv"})
+@utils.export("set", {"setting": "trakt", "help": "Set username on trakt.tv",
+    "example": "jesopo"})
 class Module(ModuleManager.BaseModule):
     @utils.hook("received.command.nw", alias_of="nowwatching")
     @utils.hook("received.command.nowwatching")

modules/tweets.py

@@ -12,7 +12,7 @@ REGEX_TWITTERURL = re.compile(
 
 @utils.export("channelset", {"setting": "auto-tweet",
     "help": "Enable/disable automatically getting tweet info",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     _name = "Twitter"
 

modules/words.py

@@ -7,7 +7,7 @@ WORD_STOP = WORD_DELIM+"”)}>;:.,!?"
 
 @utils.export("set", {"setting": "word-tracking",
     "help": "Disable/enable tracking your wordcounts",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 class Module(ModuleManager.BaseModule):
     def _channel_message(self, user, event):
         if not user.get_setting("word-tracking", True):

modules/youtube.py

@@ -18,10 +18,10 @@ ARROW_DOWN = "↓"
 
 @utils.export("channelset", {"setting": "auto-youtube",
     "help": "Disable/Enable automatically getting info from youtube URLs",
-    "validate": utils.bool_or_none})
+    "validate": utils.bool_or_none, "example": "on"})
 @utils.export("channelset", {"setting": "youtube-safesearch",
-    "help": "Turn safe search off/on",
+    "help": "Turn safe search off/on", "validate": utils.bool_or_none,
-    "validate": utils.bool_or_none})
+    "example": "on"})
 class Module(ModuleManager.BaseModule):
     def on_load(self):
         self.exports.add("search-youtube", self._search_youtube)