Improve doc, especially for copy_params and OutputLocalTarget

Change-Id: I5e4a261c37e090739de4f408a609c8070342eae6

luigi_tools/parameters.py

@@ -48,7 +48,7 @@ def normalize(self, x):
         """Ensure that the value is contained in the given interval.
 
         The ``parse()`` method is not called when the parameters are given to the constructor,
-        but the value check is only done there. This ``normalize()`` method ansures that the
+        but the value check is only done there. This ``normalize()`` method ensures that the
         interval check is made even when for arguments given to the constructor.
         """
         if x is not None:

luigi_tools/targets.py

@@ -8,7 +8,73 @@
 class OutputLocalTarget(luigi.LocalTarget):
     """A target that adds a prefix before the given path.
 
-    If prefix is not given, the current working directory is taken.
+    If ``prefix`` is not given, the current working directory is taken.
+
+    This class can be subclassed to easily create an output directory tree.
+
+    .. note::
+        If an absolute path is given to the target, the prefix is ignored.
+
+    **Usage**:
+
+    .. code-block:: python
+
+        class PathConfig(luigi.Config):
+            '''Paths config.'''
+            result_path = luigi.Parameter()
+            result_sub_path_1 = luigi.Parameter()
+            result_sub_path_2 = luigi.Parameter()
+
+        class Sub1OutputLocalTarget(OutputLocalTarget):
+            '''Specific target for first category outputs.'''
+
+        class Sub2OutputLocalTarget(OutputLocalTarget):
+            '''Specific target for second category outputs.'''
+
+        OutputLocalTarget.set_default_prefix(PathConfig().result_path)
+        Sub1OutputLocalTarget.set_default_prefix(
+            OutputLocalTarget._prefix / PathConfig().result_sub_path_1
+        )
+        Sub2OutputLocalTarget.set_default_prefix(
+            OutputLocalTarget._prefix / PathConfig().result_sub_path_2
+        )
+
+        class TaskA(luigi.Task):
+            def run(self):
+                # do something
+                # and write output
+                write_output(self.output().path)
+
+            def output(self):
+                return Sub1OutputLocalTarget("file1.dat")
+
+        class TaskB(luigi.Task):
+            def run(self):
+                # do something
+                # and write outputs
+                f1, f2, f3 = self.output()
+                write_output1(f1.path)
+                write_output2(f2.path)
+                write_output3(f3.path)
+
+            def output(self):
+                return [
+                    Sub1OutputLocalTarget("file2.dat"),
+                    Sub2OutputLocalTarget("file1.dat"),
+                    Sub2OutputLocalTarget("file2.dat"),
+                ]
+
+    Running this luigi workflow creates the following output directory tree:
+
+    .. code-block:: bash
+
+        └── result_path
+            ├── sub_path_1
+            │   ├── file1.dat
+            │   └── file2.dat
+            └── sub_path_2
+                ├── file1.dat
+                └── file2.dat
     """
 
     _prefix = None
@@ -28,7 +94,7 @@ def path(self, path):
 
     @property
     def pathlib_path(self):
-        """The path stored in this target returned as a ``pathlib.Path`` object."""
+        """The path stored in this target returned as a :class:`pathlib.Path` object."""
         if self._prefix is not None:
             return self._prefix / self._path
         else:
@@ -38,7 +104,9 @@ def pathlib_path(self):
     def set_default_prefix(cls, prefix):
         """Set the default prefix to the class.
 
-        .. warning:: This method is not thread-safe.
+        .. warning::
+            This method is not thread-safe and should not be used inside a
+            :class:`luigi.Task`.
         """
         OutputLocalTarget._reset_prefix(cls, prefix)
 

luigi_tools/tasks.py

@@ -45,7 +45,7 @@ class LogTargetMixin:
 
     .. note::
         To have an effect, this mixin must be placed to the left of the first class
-        inheriting from ``luigi.Task`` in the base class list.
+        inheriting from :class:`luigi.Task` in the base class list.
     """
 
     def __init__(self, *args, **kwargs):
@@ -126,7 +126,7 @@ def __setattr__(self, name, value):
 
 
 class ParamRef:
-    """Class to store parameter linking informations."""
+    """Class to store parameter reference informations."""
 
     def __init__(self, cls, name=None, default=_no_default_value):
         self.cls = cls
@@ -137,14 +137,23 @@ def __init__(self, cls, name=None, default=_no_default_value):
 class copy_params:
     """Copy a parameter from another Task.
 
-    If no value is given to this parameter, the value from the other task is taken.
+    This decorator take kwargs where keys are the parameter names and the values are
+    :class:`ParamRef` instances.
 
-    Differences with ``luigi.util.inherits``:
+    If no default value is given to the :class:`ParamRef`, two behaviours are possible:
 
-        * ``luigi.util.inherits`` set all other class' parameters that the current one is missing.
-          It is not possible to select a subset of parameters.
-        * ``luigi.util.inherits`` set the same value to the other class' parameter than the
-          current one's parameter. This class do not set the same value, except for global
+        * If the task inherits from the :class:`GlobalParamMixin`, the parameter is linked to the
+          one of the base class. The default parameter value is then the actual value of the
+          linked parameter.
+        * If the task does not inherit from the :class:`GlobalParamMixin`, the default value is
+          copied from the linked parameter.
+
+    Differences with :class:`luigi.util.inherits`:
+
+        * :class:`luigi.util.inherits` set all other class' parameters that the current one is
+          missing. It is not possible to select a subset of parameters.
+        * :class:`luigi.util.inherits` set the same value to the other class' parameter than the
+          current one's parameter. This class does not set the same value, except for global
           parameters with no given value.
 
     **Usage**: