Merge pull request #2617 from sopel-irc/docs-scheduling-tips

docs: add advanced tip about scheduling function calls

docs/source/plugin/advanced.rst

@@ -15,6 +15,45 @@ If something is not in here, feel free to ask about it on our IRC channel, or
 maybe open an issue with the solution if you devise one yourself.
 
 
+Running a function on a schedule
+================================
+
+Sopel provides the :func:`@plugin.interval <sopel.plugin.interval>` decorator
+to run plugin callables periodically, but plugin developers semi-frequently ask
+how to run a function at the same time every day/week.
+
+Integrating this kind of feature into Sopel's plugin API is trickier than one
+might think, and it's actually simpler to have plugins just use a library like
+`schedule`__ directly::
+
+    import schedule
+
+    from sopel import plugin
+
+
+    def scheduled_message(bot):
+        bot.say("This is the scheduled message.", "#channelname")
+
+
+    def setup(bot):
+        # schedule the message at midnight every day
+        schedule.every().day.at('00:00').do(scheduled_message, bot=bot)
+
+
+    @plugin.interval(60)
+    def run_schedule(bot):
+        schedule.run_pending()
+
+As long as the ``bot`` is passed as an argument, the scheduled function can
+access config settings or any other attributes/properties it needs.
+
+Multiple plugins all setting up their own checks with ``interval`` naturally
+creates *some* overhead, but it shouldn't be significant compared to all the
+other things happening inside a Sopel bot with numerous plugins.
+
+.. __: https://pypi.org/project/schedule/
+
+
 Restricting commands to certain channels
 ========================================
 

sopel/plugin.py

@@ -1193,10 +1193,6 @@ def rate(
 
         @rate(10, 10, 2, message='Sorry {nick}, you hit the {rate_limit_type} rate limit!')
 
-    Rate-limited functions that use scheduled future commands should import
-    :class:`threading.Timer` instead of :mod:`sched`, or rate limiting will
-    not work properly.
-
     .. versionchanged:: 8.0
 
         Optional keyword argument ``message`` was added in Sopel 8.