Work on FeaturePipeline docstrings

docs/source/_static/w2w.css

@@ -27,3 +27,7 @@ a:hover {
     max-width: 700px;
 }
 
+div.seealso {
+    background-color: #EEE;
+    border-color: #CCC;
+}

enstools/feature/pipeline.py

@@ -8,18 +8,18 @@ import xarray as xr
 
 class FeaturePipeline:
     """
-    This class encapsules the feature detection pipeline. The pipeline consists of an identification and a tracking procedure.
+    Feature detection pipeline (identification and tracking).
+
+    Parameters
+    ----------
+    proto_ref
+        Protobuf template for the representation of identified features.
+    processing_mode : {'2d', '3d'}
+        Specify if identification and tracking is performed on 2D levels or in
+        3D, per 3D block.
     """
 
     def __init__(self, proto_ref, processing_mode='2d'):
-        """
-        Specify processing mode 2d or 3d: In 2d, identification and tracking will be performed on 2d levels, in 3d per 3d block.
-
-        Parameters
-        ----------
-        proto_ref
-        processing_mode
-        """
         self.id_tech = None
         self.tr_tech = None
 
@@ -38,12 +38,12 @@ class FeaturePipeline:
 
         Parameters
         ----------
-        strategy : enstools.feature.identification.IdentificationTechnique
+        strategy : IdentificationTechnique
+            The identification strategy to use in the pipeline.
         """
         self.id_tech = strategy
         self.id_tech.pb_reference = self.pb_reference
         self.id_tech.processing_mode = self.processing_mode
-        pass
 
     def set_tracking_strategy(self, strategy: TrackingTechnique):
         """
@@ -51,23 +51,32 @@ class FeaturePipeline:
 
         Parameters
         ----------
-        strategy : enstools.feature.tracking.TrackingTechnique
+        strategy : TrackingTechnique | None
+            The tracking strategy to use in the pipeline. Set to `None` or
+            don't invoke this method at all if no tracking should be carried
+            out.
         """
         self.tr_tech = strategy
         if strategy is not None:
             self.tr_tech.pb_reference = self.pb_reference
             self.tr_tech.processing_mode = self.processing_mode
-        pass
 
     def set_data_path(self, path):
         """
         Set the path to the dataset(s) to process.
-        This function calls enstools.io.read and therefore can read directories using wildcards.
+
+        This function calls :py:func:`enstools.io.read` and therefore can read
+        directories using wildcards.
 
         Parameters
         ----------
         path : list of str or tuple of str
                 names of individual files or filename pattern
+
+        See Also
+        --------
+        :py:meth:`.set_data`
+
         """
         if path is None:
             raise Exception("None path provided.")
@@ -80,7 +89,6 @@ class FeaturePipeline:
     def set_data(self, dataset: xr.Dataset):
         """
         Set the dataset to process.
-        The function set_data_path() can be used instead.
 
         Parameters
         ----------
@@ -94,9 +102,7 @@ class FeaturePipeline:
         self.dataset_path = ""
 
     def execute_identification(self):
-        """
-        Execute the identification strategy.
-        """
+        """Execute only the identification strategy."""
         return_obj_desc_id, return_ds = self.id_tech.execute(self.dataset)
         self.object_desc = return_obj_desc_id
         if return_ds is not None:
@@ -106,14 +112,16 @@ class FeaturePipeline:
         self.object_desc.run_time = str(datetime.now().isoformat())
 
     def execute_tracking(self):
-        """
-        Execute the tracking strategy.
-        """
+        """Execute only the tracking strategy."""
         self.tr_tech.execute(self.object_desc, self.dataset)
 
     def execute(self):
         """
-        Execute the feature detection based on the set data and set techniques.
+        Execute the entire feature detection pipeline.
+
+        See Also
+        --------
+        :py:meth:`.execute_identification`, :py:meth:`.execute_tracking`
         """
         # TODO need API to check if identification output type fits to tracking input type.
 
@@ -129,10 +137,12 @@ class FeaturePipeline:
 
     def is_data_3d(self):
         """
-        Checks if provided dataset is spatially 3D (has a vertical dim)
+        Checks if the provided dataset is spatially 3D (has a vertical dim)
+
         Returns
         -------
-        True if vertical dim in dataset
+        bool
+            `True` if vertical dim in dataset else `False`.
         """
         if self.dataset is None:
             raise Exception("None dataset provided.")