Fix pydocstyle D403 (First word of the first line should be properly capitalized) in examples (#14500)

anntzer · web-flow · commit 30454d796b0a · 2019-06-11T10:43:50.000+02:00
Fix pydocstyle D403 (First word of the first line should be properly capitalized) in examples
diff --git a/examples/event_handling/path_editor.py b/examples/event_handling/path_editor.py
@@ -77,15 +77,17 @@ def draw_callback(self, event):
         self.canvas.blit(self.ax.bbox)
 
     def pathpatch_changed(self, pathpatch):
-        'this method is called whenever the pathpatchgon object is called'
+        """This method is called whenever the pathpatch object is called."""
         # only copy the artist props to the line (except visibility)
         vis = self.line.get_visible()
         plt.Artist.update_from(self.line, pathpatch)
         self.line.set_visible(vis)  # don't use the pathpatch visibility state
 
     def get_ind_under_point(self, event):
-        'get the index of the vertex under point if within epsilon tolerance'
-
+        """
+        Return the index of the point closest to the event position or *None*
+        if no point is within ``self.epsilon`` to the event position.
+        """
         # display coords
         xy = np.asarray(self.pathpatch.get_path().vertices)
         xyt = self.pathpatch.get_transform().transform(xy)
@@ -99,7 +101,7 @@ def get_ind_under_point(self, event):
         return ind
 
     def button_press_callback(self, event):
-        'whenever a mouse button is pressed'
+        """Callback for mouse button presses."""
         if not self.showverts:
             return
         if event.inaxes is None:
@@ -109,15 +111,15 @@ def button_press_callback(self, event):
         self._ind = self.get_ind_under_point(event)
 
     def button_release_callback(self, event):
-        'whenever a mouse button is released'
+        """Callback for mouse button releases."""
         if not self.showverts:
             return
         if event.button != 1:
             return
         self._ind = None
 
     def key_press_callback(self, event):
-        'whenever a key is pressed'
+        """Callback for key presses."""
         if not event.inaxes:
             return
         if event.key == 't':
@@ -129,7 +131,7 @@ def key_press_callback(self, event):
         self.canvas.draw()
 
     def motion_notify_callback(self, event):
-        'on mouse movement'
+        """Callback for mouse movements."""
         if not self.showverts:
             return
         if self._ind is None:
diff --git a/examples/event_handling/pick_event_demo.py b/examples/event_handling/pick_event_demo.py
@@ -117,9 +117,9 @@ def pick_custom_hit():
 
     def line_picker(line, mouseevent):
         """
-        find the points within a certain distance from the mouseclick in
+        Find the points within a certain distance from the mouseclick in
         data coords and attach some extra attributes, pickx and picky
-        which are the data points that were picked
+        which are the data points that were picked.
         """
         if mouseevent.xdata is None:
             return False, dict()
diff --git a/examples/event_handling/poly_editor.py b/examples/event_handling/poly_editor.py
@@ -90,15 +90,17 @@ def draw_callback(self, event):
         # updated
 
     def poly_changed(self, poly):
-        'this method is called whenever the polygon object is called'
+        """This method is called whenever the pathpatch object is called."""
         # only copy the artist props to the line (except visibility)
         vis = self.line.get_visible()
         Artist.update_from(self.line, poly)
         self.line.set_visible(vis)  # don't use the poly visibility state
 
     def get_ind_under_point(self, event):
-        'get the index of the vertex under point if within epsilon tolerance'
-
+        """
+        Return the index of the point closest to the event position or *None*
+        if no point is within ``self.epsilon`` to the event position.
+        """
         # display coords
         xy = np.asarray(self.poly.xy)
         xyt = self.poly.get_transform().transform(xy)
@@ -113,7 +115,7 @@ def get_ind_under_point(self, event):
         return ind
 
     def button_press_callback(self, event):
-        'whenever a mouse button is pressed'
+        """Callback for mouse button presses."""
         if not self.showverts:
             return
         if event.inaxes is None:
@@ -123,15 +125,15 @@ def button_press_callback(self, event):
         self._ind = self.get_ind_under_point(event)
 
     def button_release_callback(self, event):
-        'whenever a mouse button is released'
+        """Callback for mouse button releases."""
         if not self.showverts:
             return
         if event.button != 1:
             return
         self._ind = None
 
     def key_press_callback(self, event):
-        'whenever a key is pressed'
+        """Callback for key presses."""
         if not event.inaxes:
             return
         if event.key == 't':
@@ -163,7 +165,7 @@ def key_press_callback(self, event):
             self.canvas.draw_idle()
 
     def motion_notify_callback(self, event):
-        'on mouse movement'
+        """Callback for mouse movements."""
         if not self.showverts:
             return
         if self._ind is None:
diff --git a/examples/lines_bars_and_markers/filled_step.py b/examples/lines_bars_and_markers/filled_step.py
@@ -80,6 +80,8 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
                hist_func=None, labels=None,
                plot_func=None, plot_kwargs=None):
     """
+    Parameters
+    ----------
     ax : axes.Axes
         The axes to add artists too
 
diff --git a/examples/lines_bars_and_markers/markevery_demo.py b/examples/lines_bars_and_markers/markevery_demo.py
@@ -44,7 +44,9 @@
 
 
 def trim_axs(axs, N):
-    """little helper to massage the axs list to have correct length..."""
+    """
+    Reduce *axs* to *N* Axes. All further Axes are removed from the figure.
+    """
     axs = axs.flat
     for ax in axs[N:]:
         ax.remove()
diff --git a/examples/statistics/barchart_demo.py b/examples/statistics/barchart_demo.py
@@ -33,11 +33,7 @@
 
 
 def attach_ordinal(num):
-    """helper function to add ordinal string to integers
-
-    1 -> 1st
-    56 -> 56th
-    """
+    """Convert an integer to an ordinal string, e.g. 2 -> '2nd'."""
     suffixes = {str(i): v
                 for i, v in enumerate(['th', 'st', 'nd', 'rd', 'th',
                                        'th', 'th', 'th', 'th', 'th'])}
diff --git a/examples/subplots_axes_and_figures/secondary_axis.py b/examples/subplots_axes_and_figures/secondary_axis.py
@@ -119,17 +119,13 @@ def inverse(x):
 
 
 def date2yday(x):
-    """
-    x is in matplotlib datenums, so they are floats.
-    """
+    """Convert matplotlib datenum to days since 2018-01-01."""
     y = x - mdates.date2num(datetime.datetime(2018, 1, 1))
     return y
 
 
 def yday2date(x):
-    """
-    return a matplotlib datenum (x is days since start of year)
-    """
+    """Return a matplotlib datenum for *x* days after 2018-01-01."""
     y = x + mdates.date2num(datetime.datetime(2018, 1, 1))
     return y
 
diff --git a/examples/tests/backend_driver_sgskip.py b/examples/tests/backend_driver_sgskip.py
@@ -310,7 +310,7 @@
 
 
 def report_missing(dir, flist):
-    'report the py files in dir that are not in flist'
+    """Report the .py files in *dir* that are not in *flist*."""
     globstr = os.path.join(dir, '*.py')
     fnames = glob.glob(globstr)
 
diff --git a/examples/text_labels_and_annotations/demo_text_path.py b/examples/text_labels_and_annotations/demo_text_path.py
@@ -36,7 +36,7 @@ def __init__(self, path, bbox_image, **kwargs):
         self._init_bbox_image(bbox_image)
 
     def set_facecolor(self, color):
-        """simply ignore facecolor"""
+        """Simply ignore facecolor."""
         mpatches.PathPatch.set_facecolor(self, "none")
 
     def _init_bbox_image(self, im):
diff --git a/examples/units/basic_units.py b/examples/units/basic_units.py
@@ -319,7 +319,7 @@ def rad_fn(x, pos=None):
 class BasicUnitConverter(units.ConversionInterface):
     @staticmethod
     def axisinfo(unit, axis):
-        'return AxisInfo instance for x and unit'
+        """Return AxisInfo instance for x and unit."""
 
         if unit == radians:
             return units.AxisInfo(
@@ -364,7 +364,7 @@ def convert(val, unit, axis):
 
     @staticmethod
     def default_units(x, axis):
-        'return the default unit for x or None'
+        """Return the default unit for x or None."""
         if np.iterable(x):
             for thisx in x:
                 return thisx.unit
diff --git a/examples/units/evans_test.py b/examples/units/evans_test.py
@@ -30,7 +30,7 @@ def value(self, unit):
 class FooConverter(units.ConversionInterface):
     @staticmethod
     def axisinfo(unit, axis):
-        'return the Foo AxisInfo'
+        """Return the Foo AxisInfo."""
         if unit == 1.0 or unit == 2.0:
             return units.AxisInfo(
                 majloc=ticker.IndexLocator(8, 0),
@@ -44,8 +44,9 @@ def axisinfo(unit, axis):
     @staticmethod
     def convert(obj, unit, axis):
         """
-        convert obj using unit.  If obj is a sequence, return the
-        converted sequence
+        Convert *obj* using *unit*.
+
+        If *obj* is a sequence, return the converted sequence.
         """
         if units.ConversionInterface.is_numlike(obj):
             return obj
@@ -57,7 +58,7 @@ def convert(obj, unit, axis):
 
     @staticmethod
     def default_units(x, axis):
-        'return the default unit for x or None'
+        """Return the default unit for *x* or None."""
         if np.iterable(x):
             for thisx in x:
                 return thisx.unit
diff --git a/examples/widgets/menu.py b/examples/widgets/menu.py
@@ -109,7 +109,9 @@ def set_hover_props(self, b):
         self.rect.set(facecolor=props.bgcolor, alpha=props.alpha)
 
     def set_hover(self, event):
-        'check the hover status of event and return true if status is changed'
+        """
+        Update the hover status of event and return whether it was changed.
+        """
         b, junk = self.rect.contains(event)
 
         changed = (b != self.hover)
diff --git a/examples/widgets/rectangle_selector.py b/examples/widgets/rectangle_selector.py
@@ -16,7 +16,11 @@
 
 
 def line_select_callback(eclick, erelease):
-    'eclick and erelease are the press and release events'
+    """
+    Callback for line selection.
+
+    *eclick* and *erelease* are the press and release events.
+    """
     x1, y1 = eclick.xdata, eclick.ydata
     x2, y2 = erelease.xdata, erelease.ydata
     print("(%3.2f, %3.2f) --> (%3.2f, %3.2f)" % (x1, y1, x2, y2))
diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -79,9 +79,7 @@
 
 
 def plot_examples(cms):
-    """
-    helper function to plot two colormaps
-    """
+    """Helper function to plot two colormaps."""
     np.random.seed(19680801)
     data = np.random.randn(30, 30)
 
