Reorganize docs.

docs/guide.rst

@@ -398,11 +398,57 @@ API docs:
 * :py:meth:`TaskWrapper.is_revoked` for checking the status of the task
   function itself.
 
+Canceling or pausing periodic tasks
+-----------------------------------
+
+The ``revoke()`` and ``restore()`` methods support some additional options
+which may be especially useful for :py:meth:`~Huey.periodic_task`.
+
+The :py:meth:`~TaskWrapper.revoke` method accepts two optional parameters:
+
+* ``revoke_once`` - boolean flag, if set then only the next occurrence of the
+  task will be revoked, after which it will be restored automatically.
+* ``revoke_until`` - datetime, which specifies the time at which the task
+  should be automatically restored.
+
+For example, suppose we have a task that sends email notifications, but our
+mail server goes down and won't be fixed for a while. We can revoke the task
+for a couple of hours, after which time it will start executing again:
+
+.. code-block:: python
+
+    @huey.periodic_task(crontab(minute='0', hour='*'))
+    def send_notification_emails():
+        # ... code to send emails ...
+
+Here is how we might revoke the task for the next 3 hours:
+
+.. code-block:: pycon
+
+    >>> now = datetime.datetime.now()
+    >>> eta = now + datetime.timedelta(hours=3)
+    >>> send_notification_emails.revoke(revoke_until=eta)
+
+Alternatively, we could use ``revoke_once=True`` to just skip the next
+execution of the task:
+
+.. code-block:: pycon
+
+    >>> send_notification_emails.revoke(revoke_once=True)
+
+At any time, the task can be restored using the usual
+:py:meth:`~TaskWrapper.restore` method, and it's status can be checked using
+the :py:meth:`~TaskWrapper.is_revoked` method.
+
 Task expiration
 ---------------
 
 Huey tasks can be configured with an expiration time. Setting an expiration
 time on tasks will prevent them being run after the given time has elapsed.
+Expiration times may be useful if your queue is busy and there may be a
+significant lag between the time a task is enqueued and the time the consumer
+starts executing it.
+
 Expiration times can be specified as:
 
 * ``datetime()`` instances, which are treated as absolute times.
@@ -442,48 +488,6 @@ Expiration times can also be specified when scheduling tasks:
         eta=one_hr,
         expires=one_hr + timedelta(seconds=60))
 
-Canceling or pausing periodic tasks
------------------------------------
-
-The ``revoke()`` and ``restore()`` methods support some additional options
-which may be especially useful for :py:meth:`~Huey.periodic_task`.
-
-The :py:meth:`~TaskWrapper.revoke` method accepts two optional parameters:
-
-* ``revoke_once`` - boolean flag, if set then only the next occurrence of the
-  task will be revoked, after which it will be restored automatically.
-* ``revoke_until`` - datetime, which specifies the time at which the task
-  should be automatically restored.
-
-For example, suppose we have a task that sends email notifications, but our
-mail server goes down and won't be fixed for a while. We can revoke the task
-for a couple of hours, after which time it will start executing again:
-
-.. code-block:: python
-
-    @huey.periodic_task(crontab(minute='0', hour='*'))
-    def send_notification_emails():
-        # ... code to send emails ...
-
-Here is how we might revoke the task for the next 3 hours:
-
-.. code-block:: pycon
-
-    >>> now = datetime.datetime.now()
-    >>> eta = now + datetime.timedelta(hours=3)
-    >>> send_notification_emails.revoke(revoke_until=eta)
-
-Alternatively, we could use ``revoke_once=True`` to just skip the next
-execution of the task:
-
-.. code-block:: pycon
-
-    >>> send_notification_emails.revoke(revoke_once=True)
-
-At any time, the task can be restored using the usual
-:py:meth:`~TaskWrapper.restore` method, and it's status can be checked using
-the :py:meth:`~TaskWrapper.is_revoked` method.
-
 Task pipelines
 --------------