PR comments

doc/calibrations/slit_tracing.rst

@@ -121,7 +121,8 @@ moves; the horizontal line always stays at the reference row.  Note that the
 vertical line marking the cursor may not appear if the typical matplotlib zoom
 or pan buttons are active.
 
-Pressing the ``?`` key anywhere in the window will print the key bindings:
+Pressing the ``?`` key anywhere in the window will print the key bindings to the
+terminal window:
 
 .. code-block:: console
 

doc/include/links.rst

@@ -56,6 +56,8 @@
 .. _matplotlib.axes.Axes: https://matplotlib.org/api/axes_api.html#matplotlib.axes.Axes
 .. _matplotlib.image.AxesImage: https://matplotlib.org/stable/api/image_api.html#matplotlib.image.AxesImage
 .. _matplotlib.backend_bases.Event: https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.Event
+.. _matplotlib.widgets.Button.on_clicked: https://matplotlib.org/stable/api/widgets_api.html#matplotlib.widgets.Button.on_clicked
+.. _matplotlib.widgets.RangeSlider: https://matplotlib.org/stable/api/widgets_api.html#matplotlib.widgets.RangeSlider
 
 .. configobj
 .. _configobj: http://configobj.readthedocs.io/en/latest/

pypeit/core/gui/edge_inspector.py

@@ -15,11 +15,11 @@
 
 class EdgeInspectorGUI:
     """
-    Pointer used when analyzing a trace/sobel image.
+    matplotlib-based GUI to analyze/manipulate edge traces.
 
     Args:
         edges (:class:`~pypeit.edgetrace.EdgeTraceSet`):
-            Edge tracing to inspect/edit.
+            Edge tracing to inspect/edit.  Note this object is edited directly!
     """
     def __init__(self, edges):
 
@@ -141,13 +141,18 @@ def plot_traces(self):
             self.trace_plot += [self.image_plot.axes.plot(self.trace_cen[:,i], self.spec_pix,
                                                           color=color, lw=2)[0]]
 
-    def update_traces(self, *args, **kwargs):
+    def update_traces(self, *args):
         """
         Update the underlying trace data and edges object.
 
         Changes to the traces are kept by the internals until we're ready to
         "update" the edges object.  This performs the update and replots the
         trace data.
+
+        All arguments to this function are accepted but ignored.  The reason is
+        because this is the function passed to
+        `matplotlib.widgets.Button.on_clicked`_, but this function does not need
+        any of the input from the ``Button`` event.
         """
         # Offsets are "applied" by first removing the initial traces and then
         # adding new ones with the locations offset.
@@ -197,10 +202,14 @@ def _reset_traces(self):
         self.trace_cen = self.edges.edge_cen if self.edges.edge_fit is None \
                             else self.edges.edge_fit
 
-    def undo(self, pos):
+    def undo(self, *args):
         """
         Undo all operations since the last time the ``edges`` object was
         updated.
+
+        The function call includes ``*args`` because it is used as an event
+        call-back function that must support arguments passed by the event.  But
+        all of these arguments are ignored.
         """
         self._reset_traces()
         self.update_traces()
@@ -223,8 +232,11 @@ def move(self, pos):
         Move the trace nearest the cursor spatial (x) position to the cursor's
         location.
 
+        This is an event call-back function that must accept an array-like
+        object giving the pointer coordinates.
+
         Args:
-            pos (:obj:`list`):
+            pos (array-like):
                 List with x and y position of the cursor at the time of the
                 window event.
         """
@@ -243,14 +255,17 @@ def delete(self, pos):
         """
         Delete the trace nearest the cursor spatial (x) position.
 
+        This is an event call-back function that must accept an array-like
+        object giving the pointer coordinates.
+
         Args:
-            pos (:obj:`list`):
+            pos (array-like):
                 List with x and y position of the cursor at the time of the
                 window event.
         """
         # Find the nearest trace
         i = self.nearest_trace(pos[0])
-        # Set the remove it
+        # Set to remove it
         self.remove[i] = True
         # For now, simply set the line to be invisible
         self.trace_plot[i].set_visible(False)
@@ -299,8 +314,11 @@ def add_left(self, pos):
         """
         Add a new left trace nearest the cursor spatial (x) position.
 
+        This is an event call-back function that must accept an array-like
+        object giving the pointer coordinates.
+
         Args:
-            pos (:obj:`list`):
+            pos (array-like):
                 List with x and y position of the cursor at the time of the
                 window event.
         """
@@ -310,8 +328,11 @@ def add_right(self, pos):
         """
         Add a new right trace nearest the cursor spatial (x) position.
 
+        This is an event call-back function that must accept an array-like
+        object giving the pointer coordinates.
+
         Args:
-            pos (:obj:`list`):
+            pos (array-like):
                 List with x and y position of the cursor at the time of the
                 window event.
         """

pypeit/core/gui/gui_util.py

@@ -98,13 +98,16 @@ def _set_event(self, action, x, y):
         if self.action not in self.observers:
             print(f'No action: {action} ({self.name}, {x}, {y})')
             return
-        if self.action in self.observers:
-            self.observers[self.action](self.pos)
+        self.observers[self.action](self.pos)
 
     def register(self, action, func, descr=None):
         """
         Register a function to associate with a specific button or key press.
 
+        *All* functions must have the same calling sequence (see
+        :func:`_set_event`), which is that they only accept a tuple with the
+        coordinates of the cursor when the event occurred.
+
         Args:
             action (:obj:`str`):
                 The keyword for the event action to perform
@@ -148,9 +151,13 @@ def print_help(self, pos):
         """
         Print the help dialog.
 
+        This is an event call-back function that must accept an array-like
+        object giving the pointer coordinates.
+
         Args:
-            pos (list):
-                Location where the help event was triggered.  This is ignored.
+            pos (array-like):
+                List with x and y position of the cursor at the time of the
+                window event.
         """
         print('-'*50)
         print('Key bindings')
@@ -167,6 +174,8 @@ class UpdateableRangeSlider(widgets.RangeSlider):
 
     This is virtually identical to the base class, but with a few customizations
     regarding where labels are placed (or removed).
+
+    See `matplotlib.widgets.RangeSlider`_ for the argument descriptions.
     """
     def __init__(self, ax, label, valmin, valmax, valinit=None, valfmt=None, closedmin=True,
                  closedmax=True, dragging=True, valstep=None, orientation="horizontal",
@@ -186,6 +195,14 @@ def __init__(self, ax, label, valmin, valmax, valinit=None, valfmt=None, closedm
     def update_range(self, rng, label=None):
         """
         Update the slider to cover a different range.
+
+        Args:
+            rng (array-like):
+                Two-element array like object setting the new limits for the
+                slider.
+            label (:obj:`str`, optional):
+                New label for the updated slider.  If None, the label remains
+                unchanged.
         """
         self._active_handle = None
         xy = self.poly.get_xy()
@@ -233,9 +250,14 @@ def change_range(self, val):
         self.image_plot.set_clim(*val)
         pyplot.draw()
 
-    def next_image(self, *args, **kwargs):
+    def next_image(self, *args):
         """
-        Got to the next image in the list.  All arguments and keywords are ignored.
+        Got to the next image in the list.
+
+        All arguments to this function are accepted but ignored.  The reason is
+        because this is the function passed to
+        `matplotlib.widgets.Button.on_clicked`_, but this function does not need
+        any of the input from the ``Button`` event.
         """
         self.showing += 1
         if self.showing >= self.nimages: