adding docs for cron, fix #51

Author: samuelcolvin

arq/main.py

@@ -291,33 +291,35 @@ def __repr__(self):
 
 
 def cron(*,
-         dft_queue=None,
-         run_at_startup=False,
-         unique=True,
          month: Union[None, set, int]=None,
          day: Union[None, set, int]=None,
          weekday: Union[None, set, int, str]=None,
          hour: Union[None, set, int]=None,
          minute: Union[None, set, int]=None,
          second: Union[None, set, int]=0,
-         microsecond: int=123456):
+         microsecond: int=123456,
+         dft_queue=None,
+         run_at_startup=False,
+         unique=True):
     """
+    Decorator which defines a functions as a cron job, eg. it should be executed at specific times.
 
-    Decorator which defines a functions as a cron job, eg. it should be executed at specific times...
+    Workers will enqueue this job at or just after the set times. If ``unique`` is true (the default) the
+    job will only be enqueued once even if multiple workers are running.
 
     If you wish to call the function directly you can access the original function at ``<func>.direct``.
 
-    :param dft_queue: default queue to use
-    :param run_at_startup: whether to run as worker starts
-    :param unique: whether the job should be only be executed on one worker.
     :param month: month(s) to run the job on, 1 - 12
     :param day: day(s) to run the job on, 1 - 31
     :param weekday: week day(s) to run the job on, 0 - 6 or mon - sun
     :param hour: hour(s) to run the job on, 0 - 23
     :param minute: minute(s) to run the job on, 0 - 59
     :param second: second(s) to run the job on, 0 - 59
     :param microsecond: microsecond(s) to run the job on,
-        defaults to 123456 as the world is busier at the top of a second 0 - 1e6
+        defaults to 123456 as the world is busier at the top of a second, 0 - 1e6
+    :param dft_queue: default queue to use
+    :param run_at_startup: whether to run as worker starts
+    :param unique: whether the job should be only be executed once at each time
     """
 
     return lambda f: CronJob(

docs/examples/cron.py

@@ -0,0 +1,8 @@
+from arq import Actor, cron
+
+
+class FooBar(Actor):
+
+    @cron(hour={9, 12, 18}, minute=12)
+    async def foo(self):
+        print('run foo job at 9.12am, 12.12pm and 6.12pm')

docs/examples/direct_enqueuing.py

@@ -10,3 +10,4 @@ async def main():
     foobar = FooBar()
     await foobar.enqueue_job('foo', 1, 2, c=48, queue=Actor.LOW_QUEUE)
     await foobar.enqueue_job('foo', 1, 2, c=48)  # this will be queued in DEFAULT_QUEUE
+    await foobar.close()

docs/usage.rst

@@ -61,6 +61,22 @@ Where the items have the following meaning:
 * ``j_ongoing`` the number of jobs currently being performed
 * ``q_*`` the number of pending jobs in each queue
 
+Cron Jobs
+.........
+
+Functions can be scheduled to be run periodically at specific times
+
+.. literalinclude:: examples/cron.py
+
+See :meth:`arq.main.cron` for details on the available arguments and how how cron works.
+
+Usage roughly shadows `cron <https://helpmanual.io/man8/cron/>`_ except ``None`` is equivilent on ``*`` in crontab.
+As per the example sets can be used to run at multiple of the given unit.
+
+Note that ``second`` defaults to ``0`` so you don't in inadvertently run jobs every second and ``microsecond``
+defaults to ``123456`` so you don't inadvertently run jobs every microsecond and so *arq* avoids enqueuing jobs
+at the top of a second when the world is generally slightly busier.
+
 Multiple Queues
 ...............