Update docstrings to support revamped autogen script for website

The configure() methods of the built-in modules used to have docstrings
in the form of a Markdown table describing the module options. These
were removed when the new static config system came about.

Ultimately, the goal is to have the autodoc script pull directly from
the docstrings of each StaticSection child-class member (since any
module that defines config settings MUST define its own child class of
StaticSection to hold its options), but putting back the docstring
tables lets the script work between now and then.

sopel/coretasks.py

@@ -567,9 +567,9 @@ def sasl_success(bot, trigger):
 @sopel.module.thread(False)
 @sopel.module.unblockable
 def blocks(bot, trigger):
-    """Manage Sopel's blocking features.
-
-    https://github.com/sopel-irc/sopel/wiki/Making-Sopel-ignore-people
+    """
+    Manage Sopel's blocking features.\
+    See [ignore system documentation]({% link _usage/ignoring-people.md %}).
 
     """
     if not trigger.admin:

sopel/modules/admin.py

@@ -26,6 +26,12 @@ class AdminSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | hold\_ground | False | Auto-rejoin the channel after being kicked. |
+    | auto\_accept\_invite | True | Auto-join channels when invited. |
+    """
     config.define_section('admin', AdminSection)
     config.admin.configure_setting('hold_ground',
                                    "Automatically re-join after being kicked?")

sopel/modules/bugzilla.py

@@ -27,6 +27,11 @@ class BugzillaSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | domains | bugzilla.redhat.com,bugzilla.mozilla.org | A list of Bugzilla issue tracker domains |
+    """
     config.define_section('bugzilla', BugzillaSection)
     config.bugzilla.configure_setting(
         'domains',

sopel/modules/clock.py

@@ -33,6 +33,12 @@ class TimeSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | tz | America/Chicago | Preferred time zone (see <https://sopel.chat/tz>); defaults to UTC |
+    | time\_format | %Y-%m-%d - %T%Z | Preferred time format (see <http://strftime.net>) |
+    """
     config.define_section('clock', TimeSection)
     config.clock.configure_setting(
         'tz', 'Preferred time zone (https://sopel.chat/tz)')
@@ -65,7 +71,7 @@ def f_time(bot, trigger):
 def update_user(bot, trigger):
     """
     Set your preferred time zone. Most timezones will work, but it's best to
-    use one from https://sopel.chat/tz
+    use one from <https://sopel.chat/tz>.
     """
     if not pytz:
         bot.reply("Sorry, I don't have timezone support installed.")
@@ -92,7 +98,7 @@ def update_user(bot, trigger):
 @example('.gettz [nick]')
 def get_user_tz(bot, trigger):
     """
-    Gets a user's preferred time zone, will show yours if no user specified
+    Gets a user's preferred time zone; will show yours if no user specified.
     """
     if not pytz:
         bot.reply("Sorry, I don't have timezone support installed.")
@@ -115,7 +121,7 @@ def get_user_tz(bot, trigger):
 def update_user_format(bot, trigger):
     """
     Sets your preferred format for time. Uses the standard strftime format. You
-    can use http://strftime.net or your favorite search engine to learn more.
+    can use <http://strftime.net> or your favorite search engine to learn more.
     """
     tformat = trigger.group(2)
     if not tformat:
@@ -148,7 +154,7 @@ def update_user_format(bot, trigger):
 @example('.gettf [nick]')
 def get_user_format(bot, trigger):
     """
-    Gets a user's preferred time format, will show yours if no user specified
+    Gets a user's preferred time format; will show yours if no user specified.
     """
     nick = trigger.group(2)
     if not nick:
@@ -169,7 +175,7 @@ def get_user_format(bot, trigger):
 @example('.setctz America/New_York')
 def update_channel(bot, trigger):
     """
-    Set the preferred time zone for the channel.
+    Set the preferred timezone for the channel.
     """
     if bot.privileges[trigger.sender][trigger.nick] < OP:
         return
@@ -199,8 +205,8 @@ def update_channel(bot, trigger):
 @example('.getctz [channel]')
 def get_channel_tz(bot, trigger):
     """
-    Gets the preferred channel timezone, or the current channel timezone if no
-    channel given.
+    Gets the channel's preferred timezone; returns the current channel's
+    if no channel name is given.
     """
     if not pytz:
         bot.reply("Sorry, I don't have timezone support installed.")
@@ -223,7 +229,7 @@ def get_channel_tz(bot, trigger):
 def update_channel_format(bot, trigger):
     """
     Sets your preferred format for time. Uses the standard strftime format. You
-    can use http://strftime.net or your favorite search engine to learn more.
+    can use <http://strftime.net> or your favorite search engine to learn more.
     """
     if bot.privileges[trigger.sender][trigger.nick] < OP:
         return
@@ -260,8 +266,8 @@ def update_channel_format(bot, trigger):
 @example('.getctf [channel]')
 def get_channel_format(bot, trigger):
     """
-    Gets the channel's preferred time format, will return current channel's if
-    no channel name is given
+    Gets the channel's preferred time format; will return current channel's if
+    no channel name is given.
     """
 
     channel = trigger.group(2)

sopel/modules/ip.py

@@ -37,6 +37,11 @@ class GeoipSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | GeoIP\_db\_path | /home/sopel/GeoIP/ | Path to the GeoIP database files |
+    """
     config.define_section('ip', GeoipSection)
     config.ip.configure_setting('GeoIP_db_path',
                                 'Path of the GeoIP db files')

sopel/modules/meetbot.py

@@ -34,6 +34,12 @@ class MeetbotSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | meeting\_log\_path | /home/sopel/www/meetings | Path to meeting logs storage directory (should be an absolute path, accessible on a webserver) |
+    | meeting\_log\_baseurl | http://example.com/~sopel/meetings | Base URL for the meeting logs directory |
+    """
     config.define_section('meetbot', MeetbotSection)
     config.meetbot.configure_setting(
         'meeting_log_path',
@@ -148,8 +154,8 @@ def ischair(nick, channel):
 @example('.startmeeting title or .startmeeting')
 def startmeeting(bot, trigger):
     """
-    Start a meeting.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Start a meeting.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, there is already a meeting in progress here!')
@@ -198,8 +204,8 @@ def startmeeting(bot, trigger):
 @example('.subject roll call')
 def meetingsubject(bot, trigger):
     """
-    Change the meeting subject.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Change the meeting subject.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -223,8 +229,8 @@ def meetingsubject(bot, trigger):
 @example('.endmeeting')
 def endmeeting(bot, trigger):
     """
-    End a meeting.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    End a meeting.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -248,8 +254,8 @@ def endmeeting(bot, trigger):
 @example('.chairs Tyrope Jason elad')
 def chairs(bot, trigger):
     """
-    Set the meeting chairs.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Set the meeting chairs.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -272,8 +278,8 @@ def chairs(bot, trigger):
 @example('.action elad will develop a meetbot')
 def meetingaction(bot, trigger):
     """
-    Log an action in the meeting log
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Log an action in the meeting log.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -305,8 +311,8 @@ def listactions(bot, trigger):
 @example('.agreed Bowties are cool')
 def meetingagreed(bot, trigger):
     """
-    Log an agreement in the meeting log.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Log an agreement in the meeting log.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -327,8 +333,8 @@ def meetingagreed(bot, trigger):
 @example('.link http://example.com')
 def meetinglink(bot, trigger):
     """
-    Log a link in the meeing log.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Log a link in the meeing log.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -356,8 +362,8 @@ def meetinglink(bot, trigger):
 @example('.info all board members present')
 def meetinginfo(bot, trigger):
     """
-    Log an informational item in the meeting log
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+    Log an informational item in the meeting log.\
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         bot.say('Can\'t do that, start meeting first')
@@ -393,7 +399,8 @@ def take_comment(bot, trigger):
     in the meeting.
 
     Used in private message only, as `.comment <#channel> <comment to add>`
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not trigger.sender.is_nick():
         return
@@ -416,7 +423,8 @@ def take_comment(bot, trigger):
 def show_comments(bot, trigger):
     """
     Show the comments that have been logged for this meeting with .comment.
-    https://github.com/sopel-irc/sopel/wiki/Using-the-meetbot-module
+
+    See [meetbot module usage]({% link _usage/meetbot-module.md %})
     """
     if not ismeetingrunning(trigger.sender):
         return

sopel/modules/remind.py

@@ -163,10 +163,10 @@ def remind(bot, trigger):
 @example('.at 13:47 Do your homework!')
 def at(bot, trigger):
     """
-    Gives you a reminder at the given time. Takes hh:mm:ssTimezone
-    message. Timezone is any timezone Sopel takes elsewhere; the best choices
-    are those from the tzdb; a list of valid options is available at
-    https://sopel.chat/tz . The seconds and timezone are optional.
+    Gives you a reminder at the given time. Takes `hh:mm:ssTimezone message`.
+    Timezone is any timezone Sopel takes elsewhere; the best choices are those
+    from the tzdb; a list of valid options is available at
+    <https://sopel.chat/tz>. The seconds and timezone are optional.
     """
     if not trigger.group(2):
         bot.say("No arguments given for reminder command.")

sopel/modules/safety.py

@@ -51,6 +51,13 @@ class SafetySection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | enabled\_by\_default | True | Enable URL safety in all channels where it isn't explicitly disabled. |
+    | known\_good | sopel.chat,dftba.net | List of "known good" domains to ignore. |
+    | vt\_api\_key | 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | Optional VirusTotal API key to improve malicious URL detection |
+    """
     config.define_section('safety', SafetySection)
     config.safety.configure_setting(
         'enabled_by_default',

sopel/modules/url.py

@@ -39,6 +39,13 @@ class UrlSection(StaticSection):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | exclude | https?://git\\\\.io/.* | A list of regular expressions for URLs for which the title should not be shown. |
+    | exclusion\_char | ! | A character (or string) which, when immediately preceding a URL, will stop the URL's title from being shown. |
+    | shorten\_url\_length | 72 | If greater than 0, the title fetcher will include a TinyURL version of links longer than this many characters. |
+    """
     config.define_section('url', UrlSection)
     config.url.configure_setting(
         'exclude',

sopel/modules/wikipedia.py

@@ -37,6 +37,12 @@ def setup(bot):
 
 
 def configure(config):
+    """
+    | name | example | purpose |
+    | ---- | ------- | ------- |
+    | default\_lang | en | The default language to find articles from (same as Wikipedia language subdomain) |
+    | lang\_per\_channel | #YourPants:en,#TusPantalones:es | List of #channel:langcode pairs to define Wikipedia language per channel |
+    """
     config.define_section('wikipedia', WikipediaSection)
     config.wikipedia.configure_setting(
         'default_lang',