Add docstrings throughout

Author: dstansby

pyproject.toml

@@ -14,7 +14,21 @@ profile = "black"
 line_length = 79
 
 [tool.ruff]
-
 target-version = "py38"
-select = ["I", "UP", "F", "E", "W"]
+select = ["I", "UP", "F", "E", "W", "D"]
+ignore = [
+    "D100", # Missing docstring in public module
+    "D200", # One-line docstring should fit on one line
+    "D205", # 1 blank line required between summary line and description
+    "D400", # First line should end with a period
+    "D401", # First line of docstring should be in imperative mood
+]
 fix = true
+
+[tool.ruff.per-file-ignores]
+"docs/*" = ["D"]
+"examples/*" = ["D"]
+"src/napari_matplotlib/tests/*" = ["D"]
+
+[tool.ruff.pydocstyle]
+convention = "numpy"

src/napari_matplotlib/base.py

@@ -30,8 +30,7 @@
 
 class NapariMPLWidget(QWidget):
     """
-    Base widget that can be embedded as a napari widget and contains a
-    Matplotlib canvas.
+    Base Matplotlib canvas. widget that can be embedded as a napari widget.
 
     This creates a single FigureCanvas, which contains a single Figure.
 
@@ -90,7 +89,9 @@ def current_z(self) -> int:
 
     def setup_callbacks(self) -> None:
         """
-        Setup callbacks for:
+        Sets up callbacks.
+
+        Sets up callbacks for:
         - Layer selection changing
         - z-step changing
         """
@@ -135,7 +136,7 @@ def draw(self) -> None:
 
     def _on_update_layers(self) -> None:
         """
-        This function is called when self.layers is updated via
+        Function is called when self.layers is updated via
         ``self.update_layers()``.
 
         This is a no-op, and is intended for derived classes to override.

src/napari_matplotlib/histogram.py

@@ -25,6 +25,9 @@ def __init__(self, napari_viewer: napari.viewer.Viewer):
         self.update_layers(None)
 
     def clear(self) -> None:
+        """
+        Clear the axes.
+        """
         self.axes.clear()
 
     def draw(self) -> None:

src/napari_matplotlib/scatter.py

@@ -13,6 +13,10 @@
 
 
 class ScatterBaseWidget(NapariMPLWidget):
+    """
+    Base class for widgets that scatter two datasets against each other.
+    """
+
     # opacity value for the markers
     _marker_alpha = 0.5
 
@@ -90,7 +94,8 @@ class ScatterWidget(ScatterBaseWidget):
     input_layer_types = (napari.layers.Image,)
 
     def _get_data(self) -> Tuple[List[np.ndarray], str, str]:
-        """Get the plot data.
+        """
+        Get the plot data.
 
         Returns
         -------
@@ -109,6 +114,10 @@ def _get_data(self) -> Tuple[List[np.ndarray], str, str]:
 
 
 class FeaturesScatterWidget(ScatterBaseWidget):
+    """
+    Widget to scatter data stored in two layer feature attributes.
+    """
+
     n_layers_input = Interval(1, 1)
     # All layers that have a .features attributes
     input_layer_types = (
@@ -132,7 +141,9 @@ def __init__(self, napari_viewer: napari.viewer.Viewer):
 
     @property
     def x_axis_key(self) -> Optional[str]:
-        """Key to access x axis data from the FeaturesTable"""
+        """
+        Key to access x axis data from the FeaturesTable.
+        """
         return self._x_axis_key
 
     @x_axis_key.setter
@@ -142,16 +153,23 @@ def x_axis_key(self, key: Optional[str]) -> None:
 
     @property
     def y_axis_key(self) -> Optional[str]:
-        """Key to access y axis data from the FeaturesTable"""
+        """
+        Key to access y axis data from the FeaturesTable.
+        """
         return self._y_axis_key
 
     @y_axis_key.setter
     def y_axis_key(self, key: Optional[str]) -> None:
+        """
+        Set the y-axis key.
+        """
         self._y_axis_key = key
         self._draw()
 
     def _set_axis_keys(self, x_axis_key: str, y_axis_key: str) -> None:
-        """Set both axis keys and then redraw the plot"""
+        """
+        Set both axis keys and then redraw the plot.
+        """
         self._x_axis_key = x_axis_key
         self._y_axis_key = y_axis_key
         self._draw()
@@ -174,7 +192,8 @@ def _get_valid_axis_keys(
             return self.layers[0].features.keys()
 
     def _get_data(self) -> Tuple[List[np.ndarray], str, str]:
-        """Get the plot data.
+        """
+        Get the plot data.
 
         Returns
         -------
@@ -213,8 +232,7 @@ def _get_data(self) -> Tuple[List[np.ndarray], str, str]:
 
     def _on_update_layers(self) -> None:
         """
-        This is called when the layer selection changes by
-        ``self.update_layers()``.
+        Called when the layer selection changes by ``self.update_layers()``.
         """
         if hasattr(self, "_key_selection_widget"):
             self._key_selection_widget.reset_choices()

src/napari_matplotlib/slice.py

@@ -50,6 +50,9 @@ def __init__(self, napari_viewer: napari.viewer.Viewer):
 
     @property
     def layer(self):
+        """
+        Layer being plotted.
+        """
         return self.layers[0]
 
     @property
@@ -70,6 +73,9 @@ def current_dim_index(self) -> int:
 
     @property
     def selector_values(self) -> Dict[str, int]:
+        """
+        Values of the slice selectors.
+        """
         return {d: self.slice_selectors[d].value() for d in _dims_sel}
 
     def update_slice_selectors(self) -> None:
@@ -107,6 +113,9 @@ def get_xy(self) -> Tuple[np.ndarray, np.ndarray]:
         return x, y
 
     def clear(self) -> None:
+        """
+        Clear the axes.
+        """
         self.axes.cla()
 
     def draw(self) -> None:

src/napari_matplotlib/tests/test_scatter.py

@@ -34,7 +34,7 @@ def make_labels_layer_with_features():
 
 
 def test_features_scatter_get_data(make_napari_viewer):
-    """test the get data method"""
+    """Test the get data method"""
     # make the label image
     label_image, feature_table = make_labels_layer_with_features()
 
@@ -59,7 +59,7 @@ def test_features_scatter_get_data(make_napari_viewer):
 
 
 def test_get_valid_axis_keys(make_napari_viewer):
-    """test the values returned from
+    """Test the values returned from
     FeaturesScatterWidget._get_valid_keys() when there
     are valid keys.
     """
@@ -76,7 +76,7 @@ def test_get_valid_axis_keys(make_napari_viewer):
 
 
 def test_get_valid_axis_keys_no_valid_keys(make_napari_viewer):
-    """test the values returned from
+    """Test the values returned from
     FeaturesScatterWidget._get_valid_keys() when there
     are not valid keys.
     """

src/napari_matplotlib/util.py

@@ -2,6 +2,10 @@
 
 
 class Interval:
+    """
+    An integer interval.
+    """
+
     def __init__(self, lower_bound: Optional[int], upper_bound: Optional[int]):
         """
         Parameters
@@ -19,7 +23,10 @@ def __init__(self, lower_bound: Optional[int], upper_bound: Optional[int]):
         self.lower = lower_bound
         self.upper = upper_bound
 
-    def __contains__(self, val):
+    def __contains__(self, val: int) -> bool:
+        """
+        Return True if val is in the current interval.
+        """
         if not isinstance(val, int):
             raise ValueError("variable must be an integer")
         if self.lower is not None and val < self.lower: