Added documentation regarding corutines

AUTHORS.rst

@@ -32,4 +32,5 @@ Thanks to all the wonderful folks who have contributed to schedule over the year
 - ebllg <https://github.com/ebllg>
 - fredthomsen <https://github.com/fredthomsen>
 - biggerfisch <https://github.com/biggerfisch>
-- sosolidkk <https://github.com/sosolidkk>
+- sosolidkk <https://github.com/sosolidkk>
+- 07pepa <https://github.com/07pepa>

docs/asyncio.rst

@@ -0,0 +1,52 @@
+Asyncio & Coroutines
+====================
+
+This example shows how to schedule an async job on the asyncio event loop.
+
+.. code-block:: python
+
+    import schedule
+    import asyncio
+
+    async def job_async():
+        print("I am an async job")
+        await asyncio.sleep(1)
+
+    schedule.every(5).seconds.do(lambda: asyncio.create_task(job_async()))
+
+    async def scheduler():
+        while True:
+            await asyncio.sleep(1)
+            schedule.run_pending()
+
+    asyncio.run(scheduler())
+
+The call to ``asyncio.create_task()`` submits the ``job_async`` coroutine to the asyncio event loop.
+It may or may not run immediately, depending on the how busy the event loop is.
+
+Sleeping the right amount of time
+---------------------------------
+
+The ``scheduler()`` can be optimized by sleeping *exactly* [1]_ the amount of time until the next job is scheduled to run:
+
+.. code-block:: python
+
+    async def scheduler():
+        seconds = schedule.idle_seconds()
+        while seconds is not None:
+            if seconds > 0:
+                # sleep exactly the right amount of time
+                await asyncio.sleep(seconds)
+            schedule.run_pending()
+            seconds = schedule.idle_seconds()
+
+    asyncio.run(scheduler())
+
+Keep in mind that if a new job is scheduled while sleeping, the new job's earliest run is whenever the sleep finishes.
+
+More examples
+-------------
+More advanced usage examples of schedule and asyncio can be found in `this thread <https://github.com/dbader/schedule/issues/388>`_.
+
+.. rubric:: Footnotes
+.. [1] `asyncio.sleep` may sleep little more then expected, depending on loop implementation of loop and system load.

docs/examples.rst

@@ -260,15 +260,13 @@ Returns ``None`` if no jobs are scheduled.
 
     schedule.every(5).seconds.do(job)
 
-    while 1:
-        n = schedule.idle_seconds()
-        if n is None:
-            # no more jobs
-            break
-        elif n > 0:
+    seconds = schedule.idle_seconds()
+    while seconds is not None: #None= no more jobs
+        if n > 0:
             # sleep exactly the right amount of time
             time.sleep(n)
         schedule.run_pending()
+        seconds = schedule.idle_seconds()
 
 
 Run all jobs now, regardless of their scheduling

docs/faq.rst

@@ -68,6 +68,17 @@ How to continuously run the scheduler without blocking the main thread?
 -----------------------------------------------------------------------
 :doc:`Background Execution<background-execution>`.
 
+Does schedule support asyncio coroutines?
+-----------------------------------------
+Schedule does not accept coroutines as jobs directly yet.
+However, using using ``asyncio.create_task`` you able to schedule async jobs.
+See :doc:`this page <asyncio>` for an example.
+
+What happens when my computer hibernates during time.sleep/wait
+----------------------------------------------------------------
+Depending on python version it may behave erratically in undocumented ways `see <https://bugs.python.org/issue43821?@ok_message=msg%20390914%20createdissue%2043821%20created&@template=item>`_
+in future this may be resolved by asyncio
+
 Another question?
 -----------------
 If you are left with an unanswered question, `browse the issue tracker <http://github.com/dbader/schedule/issues>`_ to see if your question has been asked before.

docs/index.rst

@@ -16,11 +16,12 @@ Python job scheduling for humans. Run Python functions (or any other callable) p
 - A simple to use API for scheduling jobs, made for humans.
 - In-process scheduler for periodic jobs. No extra processes needed!
 - Very lightweight and no external dependencies.
+- Works with :doc:`asyncio coroutines<asyncio>`
 - Excellent test coverage.
 - Tested on Python 3.6, 3.7, 3.8 and 3.9
 
 
-:doc:`Example <examples>`
+:doc:`Example<examples>`
 -------------------------
 
 .. code-block:: bash
@@ -75,6 +76,7 @@ Read More
    examples
    background-execution
    parallel-execution
+   asyncio
    exception-handling
    logging
    multiple-schedulers