Added documentation for the new behavior of container_output option.

alpaca/decorator.py

@@ -69,18 +69,55 @@ class Provenance(object):
         data structures used by the function). Alpaca will track and identify
         the elements inside the container, instead of the container itself.
         Default: None
-    container_output : bool or int, optional
+    container_output : bool or int or tuple, optional
         The function outputs data inside a container (e.g., a list).
+
         If True, Alpaca will track and identify the elements inside the
         container, instead of the container itself. It will iterate over the
         function output object and identify the individual elements. However,
         for dictionary outputs, the dictionary object is identified together
         with its elements, to retain information on the keys. For other
         containers, the container object is not identified.
+
         If an integer, this defines a multiple-level (nested) container. The
         number defines the depth for which to identify and serialize the
         objects. In this case, the function output object will always be
-        identified together with the element tree.
+        identified together with the element tree. For instance, consider
+        the two-level list `L = [[obj1, obj2], [obj3, obj4]]`. With
+        `container_output=0`, there will be a single function output node for
+        list `L`. Starting from `L`, there will be two additional nodes for
+        each of the inner lists (`L[0]` and `L[1]`, i.e., all elements from
+        level zero). With `container_output=1`, there will be a single
+        function output node for list `L`. Starting from `L`, there
+        will be two additional nodes for each of the inner lists (`L[0]` and
+        `L[1]`). Finally, starting from each inner list, there will be output
+        nodes for `obj1` and `obj2` (linked to `L[0]`) and for `obj3` and
+        `obj4` (linked to `L[1]`). Therefore, all elements from level one are
+        identified, and linked to the respective elements from level zero.
+
+        If a tuple, this defines a range of the levels in a nested container
+        to consider when identifying the objects output by the function. For
+        example, taking the same list above, a `container_output=(0, 1)` will
+        start from level zero and stop at the elements from level
+        one (similar to `container_output=1`). With `container_output=(1, 1)`,
+        the first level will be ignored as function output. The function will
+        have two output nodes (directly for `L[0]` and `L[1]`). Starting from
+        each inner list, there will be output nodes for `obj1` and `obj2`
+        (linked to `L[0]`) and for `obj3` and `obj4` (linked to `L[1]`).
+        Therefore, the first level (zero) of the container is ignored, and only
+        elements from level one are described. The range feature is useful for
+        functions where the relevant outputs are containers whose elements
+        should also be described, but those containers are grouped inside a
+        single return list instead of the function returning a tuple with the
+        containers.
+
+        It is important to note that all levels identified as integers or
+        range tuples should point to levels in the nested-container that
+        contain iterables. For example, in the list `L` above, the level 2
+        are the objects `objX`. If `container_output=2`, Alpaca will try to
+        iterate over each `objX` and describe their elements. If they are
+        not iterable, an error will be raised.
+
         Default: False
 
     Attributes