Doc improvements, and removes useless Signature.link example (Issue #1950)

docs/userguide/canvas.rst

@@ -419,39 +419,6 @@ The linked task will be applied with the result of its parent
 task as the first argument, which in the above case will result
 in ``mul(4, 16)`` since the result is 4.
 
-The results will keep track of what subtasks a task applies,
-and this can be accessed from the result instance::
-
-    >>> res.children
-    [<AsyncResult: 8c350acf-519d-4553-8a53-4ad3a5c5aeb4>]
-
-    >>> res.children[0].get()
-    64
-
-The result instance also has a :meth:`~@AsyncResult.collect` method
-that treats the result as a graph, enabling you to iterate over
-the results::
-
-    >>> list(res.collect())
-    [(<AsyncResult: 7b720856-dc5f-4415-9134-5c89def5664e>, 4),
-     (<AsyncResult: 8c350acf-519d-4553-8a53-4ad3a5c5aeb4>, 64)]
-
-By default :meth:`~@AsyncResult.collect` will raise an
-:exc:`~@IncompleteStream` exception if the graph is not fully
-formed (one of the tasks has not completed yet),
-but you can get an intermediate representation of the graph
-too::
-
-    >>> for result, value in res.collect(intermediate=True)):
-    ....
-
-You can link together as many tasks as you like,
-and signatures can be linked too::
-
-    >>> s = add.s(2, 2)
-    >>> s.link(mul.s(4))
-    >>> s.link(log_result.s())
-
 You can also add *error callbacks* using the ``link_error`` argument::
 
     >>> add.apply_async((2, 2), link_error=log_error.s())
@@ -508,11 +475,51 @@ work your way up the chain to get intermediate results::
     >>> res.parent.parent
     <AsyncResult: eeaad925-6778-4ad1-88c8-b2a63d017933>
 
-
 Chains can also be made using the ``|`` (pipe) operator::
 
     >>> (add.s(2, 2) | mul.s(8) | mul.s(10)).apply_async()
 
+.. note::
+
+    It's not possible to synchronize on groups, so a group chained to another
+    signature is automatically upgraded to a chord:
+
+    .. code-block:: python
+
+        # will actually be a chord when finally evaluated
+        res = (group(add.s(i, i) for i in range(10)) | xsum.s()).delay()
+
+Trails
+~~~~~~
+
+Tasks will keep track of what subtasks a task calls in the
+result backend (unless disabled using :attr:`Task.trail <~@Task.trail>`)
+and this can be accessed from the result instance::
+
+    >>> res.children
+    [<AsyncResult: 8c350acf-519d-4553-8a53-4ad3a5c5aeb4>]
+
+    >>> res.children[0].get()
+    64
+
+The result instance also has a :meth:`~@AsyncResult.collect` method
+that treats the result as a graph, enabling you to iterate over
+the results::
+
+    >>> list(res.collect())
+    [(<AsyncResult: 7b720856-dc5f-4415-9134-5c89def5664e>, 4),
+     (<AsyncResult: 8c350acf-519d-4553-8a53-4ad3a5c5aeb4>, 64)]
+
+By default :meth:`~@AsyncResult.collect` will raise an
+:exc:`~@IncompleteStream` exception if the graph is not fully
+formed (one of the tasks has not completed yet),
+but you can get an intermediate representation of the graph
+too::
+
+    >>> for result, value in res.collect(intermediate=True)):
+    ....
+
+
 Graphs
 ~~~~~~
 

docs/userguide/tasks.rst

@@ -523,6 +523,16 @@ General
 
         Logged with severity ``ERROR``, with traceback included.
 
+.. attribute:: Task.trail
+
+    By default the task will keep track of subtasks called
+    (``task.request.children``), and this will be stored with the final result
+    in the result backend, available to the client via
+    ``AsyncResult.children``.
+
+    This list of task can grow quite big for tasks starting many subtasks,
+    and you can set this attribute to False to disable it.
+
 .. attribute:: Task.default_retry_delay
 
     Default time in seconds before a retry of the task