Fix docstrings affected by move to dynamic pyplot.

anntzer · anntzer · commit 6b8438e03970 · 2017-09-08T22:25:12.000-07:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -230,7 +230,7 @@ def get_ylabel(self):
 
     def set_ylabel(self, ylabel, fontdict=None, labelpad=None, **kwargs):
         """
-        Set the label for the yaxis
+        Set the label for the yaxis.
 
         Parameters
         ----------
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1488,45 +1488,40 @@ def apply_aspect(self, position=None):
                 self.set_xbound((x0, x1))
 
     def axis(self, *v, **kwargs):
-        """Set axis properties.
+        """Convenience method to get or set axis properties.
 
         Valid signatures::
 
-          xmin, xmax, ymin, ymax = axis()
-          xmin, xmax, ymin, ymax = axis(list_arg)
-          xmin, xmax, ymin, ymax = axis(string_arg)
-          xmin, xmax, ymin, ymax = axis(**kwargs)
+          xmin, xmax, ymin, ymax = axis(*, emit=True)
+          xmin, xmax, ymin, ymax = axis(_string_arg_, *, emit=True)
+          xmin, xmax, ymin, ymax = axis([xmin, ymin, xmax, ymax], *, emit=True)
 
         Parameters
         ----------
-        v : list of float or {'on', 'off', 'equal', 'tight', 'scaled',\
-            'normal', 'auto', 'image', 'square'}
-            Optional positional argument
-
-            Axis data limits set from a list; or a command relating to axes:
-
-                ========== ================================================
-                Value      Description
-                ========== ================================================
-                'on'       Toggle axis lines and labels on
-                'off'      Toggle axis lines and labels off
-                'equal'    Equal scaling by changing limits
-                'scaled'   Equal scaling by changing box dimensions
-                'tight'    Limits set such that all data is shown
-                'auto'     Automatic scaling, fill rectangle with data
-                'normal'   Same as 'auto'; deprecated
-                'image'    'scaled' with axis limits equal to data limits
-                'square'   Square plot; similar to 'scaled', but initially\
-                           forcing xmax-xmin = ymax-ymin
-                ========== ================================================
-
-        emit : bool, optional
-            Passed to set_{x,y}lim functions, if observers
-            are notified of axis limit change
+        _string_arg_ : str, optional
+
+            The following values are allowed:
+
+            ========== =======================================================
+            Value      Description
+            ========== =======================================================
+            'on'       Toggle axis lines and labels on
+            'off'      Toggle axis lines and labels off
+            'equal'    Equal scaling by changing limits
+            'scaled'   Equal scaling by changing box dimensions
+            'tight'    Limits set such that all data is shown
+            'auto'     Automatic scaling, fill rectangle with data
+            'image'    'scaled' with axis limits equal to data limits
+            'square'   Square plot; similar to 'scaled', but initially forcing
+                       ``xmax-xmin = ymax-ymin``
+            ========== =======================================================
 
         xmin, ymin, xmax, ymax : float, optional
             The axis limits to be set
 
+        emit : bool, optional
+            Whether observers are notified of axes limit changes.
+
         Returns
         -------
         xmin, xmax, ymin, ymax : float
@@ -1547,17 +1542,15 @@ def axis(self, *v, **kwargs):
                 self.set_axis_on()
             elif s == 'off':
                 self.set_axis_off()
-            elif s in ('equal', 'tight', 'scaled', 'normal',
-                       'auto', 'image', 'square'):
+            elif s in ['equal', 'tight', 'scaled', 'auto', 'image', 'square']:
                 self.set_autoscale_on(True)
                 self.set_aspect('auto')
                 self.autoscale_view(tight=False)
-                # self.apply_aspect()
                 if s == 'equal':
                     self.set_aspect('equal', adjustable='datalim')
                 elif s == 'scaled':
                     self.set_aspect('equal', adjustable='box', anchor='C')
-                    self.set_autoscale_on(False)  # Req. by Mark Bakker
+                    self.set_autoscale_on(False)
                 elif s == 'tight':
                     self.autoscale_view(tight=True)
                     self.set_autoscale_on(False)
@@ -2950,7 +2943,7 @@ def get_xscale(self):
 
     def set_xscale(self, value, **kwargs):
         """
-        Set the x-axis scale
+        Set the x-axis scale.
 
         Parameters
         ----------
@@ -3257,7 +3250,7 @@ def get_yscale(self):
 
     def set_yscale(self, value, **kwargs):
         """
-        Set the y-axis scale
+        Set the y-axis scale.
 
         Parameters
         ----------
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1564,7 +1564,7 @@ def _set_artist_props(self, a):
     @docstring.dedent_interpd
     def gca(self, **kwargs):
         """
-        Get the current axes, creating one if necessary
+        Get the current axes, creating one if necessary.
 
         The following kwargs are supported for ensuring the returned axes
         adheres to the given projection etc., and for axes creation if
@@ -1610,17 +1610,14 @@ def gca(self, **kwargs):
         return self.add_subplot(1, 1, 1, **kwargs)
 
     def sca(self, a):
-        'Set the current axes to be a and return a'
+        """Set the current axes to be a and return a."""
         self._axstack.bubble(a)
         for func in self._axobservers:
             func(self)
         return a
 
     def _gci(self):
-        """
-        helper for :func:`~matplotlib.pyplot.gci`;
-        do not use elsewhere.
-        """
+        """Get the current colorable artist."""
         # Look first for an image in the current Axes:
         cax = self._axstack.current_key_axes()[1]
         if cax is None:
@@ -1974,20 +1971,20 @@ def get_tightbbox(self, renderer):
     def tight_layout(self, renderer=None, pad=1.08, h_pad=None, w_pad=None,
                      rect=None):
         """
-        Adjust subplot parameters to give specified padding.
-
-        Parameters:
+        Automatically adjust subplot parameters to give specified padding.
 
-          pad : float
-            padding between the figure edge and the edges of subplots,
-            as a fraction of the font-size.
-          h_pad, w_pad : float
-            padding (height/width) between edges of adjacent subplots.
+        Parameters
+        ----------
+        pad : float, optional
+            Padding between the figure edge and the edges of subplots, as a
+            fraction of the font-size.
+        h_pad, w_pad : float, optional
+            Padding (height/width) between edges of adjacent subplots.
             Defaults to `pad_inches`.
-          rect : if rect is given, it is interpreted as a rectangle
-            (left, bottom, right, top) in the normalized figure
-            coordinate that the whole subplots area (including
-            labels) will fit into. Default is (0, 0, 1, 1).
+        rect : Tuple[float, float, float, float], optional
+            (left, bottom, right, top) rectangle in normalized figure
+            coordinates that the whole subplots area (including labels) will
+            fit into.  Defaults to using the entire figure.
         """
 
         from .tight_layout import (
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -113,11 +113,11 @@ def _backend_selection():
 
 def install_repl_displayhook():
     """
-    Install a repl display hook so that any stale figure are automatically
-    redrawn when control is returned to the repl.
+    Install a REPL display hook so that any stale figure are automatically
+    redrawn when control is returned to the REPL.
 
-    This works with IPython terminals and kernels,
-    as well as vanilla python shells.
+    This works with IPython terminals and kernels, as well as vanilla Python
+    shells.
     """
     global _IP_REGISTERED
     global _INSTALL_FIG_OBSERVER
@@ -167,7 +167,7 @@ def post_execute():
 
 def uninstall_repl_displayhook():
     """
-    Uninstalls the matplotlib display hook.
+    Uninstall the matplotlib display hook.
 
     .. warning
 
@@ -823,7 +823,7 @@ def subplot(*args, **kwargs):
 def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
              subplot_kw=None, gridspec_kw=None, **fig_kw):
     """
-    Create a figure and a set of subplots
+    Create a figure and a set of subplots.
 
     This utility wrapper makes it convenient to create common layouts of
     subplots, including the enclosing figure object, in a single call.
@@ -1628,13 +1628,15 @@ def pad(s, l):
     max_name = 0
     max_summary = 0
     for name in commands:
-        doc = globals()[name].__doc__
+        func = globals()[name]
+        doc = inspect.getdoc(func)
         summary = ''
         if doc is not None:
             match = first_sentence.match(doc)
             if match is not None:
                 summary = match.group(0).strip().replace('\n', ' ')
-        name = '`%s`' % name
+        name = ("`{0.__name__}`" if func.__module__ == __name__
+                else "`~{0.__module__}.{0.__name__}`").format(func)
         rows.append([name, summary])
         max_name = max(max_name, len(name))
         max_summary = max(max_summary, len(summary))
