Start replacing ACCEPTS table by parsing numpydoc.

anntzer · anntzer · commit 275029329f67 · 2018-05-26T01:54:47.000-07:00
In most cases, we can just look for 'param : type' in the docstring.

We let ACCEPTS still have the priority to handle weird cases such as
set_xlim where we document the first arg as "bottom", but it's "bottom,
top" for the purpose of the ACCEPTS table; resolving *that* problem is
punted to later.

Only removed a few ACCEPTS entries as a proof of principle.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1054,17 +1054,16 @@ def mouseover(self, val):
 
 class ArtistInspector(object):
     """
-    A helper class to inspect an :class:`~matplotlib.artist.Artist`
-    and return information about it's settable properties and their
-    current values.
+    A helper class to inspect an :class:`~matplotlib.artist.Artist` and return
+    information about its settable properties and their current values.
     """
+
     def __init__(self, o):
         """
-        Initialize the artist inspector with an
-        :class:`~matplotlib.artist.Artist` or iterable of :class:`Artists`.
-        If an iterable is used, we assume it is a homogeneous sequence (all
-        :class:`Artists` are of the same type) and it is your responsibility
-        to make sure this is so.
+        Initialize the artist inspector with an `Artist` or an iterable of
+        `Artist`\s.  If an iterable is used, we assume it is a homogeneous
+        sequence (all `Artists` are of the same type) and it is your
+        responsibility to make sure this is so.
         """
         if not isinstance(o, Artist):
             if cbook.iterable(o):
@@ -1135,6 +1134,14 @@ def get_valid_values(self, attr):
         match = self._get_valid_values_regex.search(docstring)
         if match is not None:
             return re.sub("\n *", " ", match.group(1))
+
+        # Much faster than list(inspect.signature(func).parameters)[1],
+        # although barely relevant wrt. matplotlib's total import time.
+        param_name = func.__code__.co_varnames[1]
+        match = re.search("(?m)^ *{} : (.+)".format(param_name), docstring)
+        if match:
+            return match.group(1)
+
         return 'unknown'
 
     def _get_setters_and_targets(self):
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -602,8 +602,6 @@ def set_figure(self, fig):
         """
         Set the `.Figure` for this `.Axes`.
 
-        .. ACCEPTS: `.Figure`
-
         Parameters
         ----------
         fig : `.Figure`
@@ -907,14 +905,9 @@ def set_axes_locator(self, locator):
         """
         Set the axes locator.
 
-        .. ACCEPTS: a callable object which takes an axes instance and
-           renderer and returns a bbox.
-
         Parameters
         ----------
-        locator : callable
-            A locator function, which takes an axes and a renderer and returns
-            a bbox.
+        locator : Callable[[Axes, Renderer], Bbox]
         """
         self._axes_locator = locator
         self.stale = True
@@ -1022,10 +1015,10 @@ def cla(self):
             except TypeError:
                 pass
         # update the minor locator for x and y axis based on rcParams
-        if (rcParams['xtick.minor.visible']):
+        if rcParams['xtick.minor.visible']:
             self.xaxis.set_minor_locator(mticker.AutoMinorLocator())
 
-        if (rcParams['ytick.minor.visible']):
+        if rcParams['ytick.minor.visible']:
             self.yaxis.set_minor_locator(mticker.AutoMinorLocator())
 
         if self._sharex is None:
@@ -1125,9 +1118,8 @@ def get_facecolor(self):
     get_fc = get_facecolor
 
     def set_facecolor(self, color):
-        """Set the Axes facecolor.
-
-        .. ACCEPTS: color
+        """
+        Set the Axes facecolor.
 
         Parameters
         ----------
@@ -1314,8 +1306,6 @@ def set_adjustable(self, adjustable, share=False):
             If ``True``, apply the settings to all shared Axes.
             Default is ``False``.
 
-        .. ACCEPTS: [ 'box' | 'datalim']
-
         See Also
         --------
         matplotlib.axes.Axes.set_aspect
@@ -2132,8 +2122,6 @@ def set_autoscale_on(self, b):
         """
         Set whether autoscaling is applied on plot commands
 
-        .. ACCEPTS: bool
-
         Parameters
         ----------
         b : bool
@@ -2145,8 +2133,6 @@ def set_autoscalex_on(self, b):
         """
         Set whether autoscaling for the x-axis is applied on plot commands
 
-        .. ACCEPTS: bool
-
         Parameters
         ----------
         b : bool
@@ -2157,8 +2143,6 @@ def set_autoscaley_on(self, b):
         """
         Set whether autoscaling for the y-axis is applied on plot commands
 
-        .. ACCEPTS: bool
-
         Parameters
         ----------
         b : bool
@@ -2200,8 +2184,6 @@ def set_xmargin(self, m):
         I.e. for a data range [0, 2], a factor of ``m = -0.1`` will result in
         a range [0.2, 1.8].
 
-        .. ACCEPTS: float greater than -0.5
-
         Parameters
         ----------
         m : float greater than -0.5
@@ -2224,8 +2206,6 @@ def set_ymargin(self, m):
         I.e. for a data range [0, 2], a factor of ``m = -0.1`` will result in
         a range [0.2, 1.8].
 
-        .. ACCEPTS: float greater than -0.5
-
         Parameters
         ----------
         m : float greater than -0.5
@@ -2306,8 +2286,6 @@ def set_rasterization_zorder(self, z):
         z : float or None
             zorder below which artists are rasterized.  ``None`` means that
             artists do not get rasterized based on zorder.
-
-            .. ACCEPTS: float or None
         """
         self._rasterization_zorder = z
         self.stale = True
@@ -2636,8 +2614,6 @@ def set_frame_on(self, b):
         """
         Set whether the axes rectangle patch is drawn.
 
-        .. ACCEPTS: bool
-
         Parameters
         ----------
         b : bool
@@ -2655,8 +2631,6 @@ def set_axisbelow(self, b):
         """
         Set whether axis ticks and gridlines are above or below most artists.
 
-        .. ACCEPTS: [ bool | 'line' ]
-
         Parameters
         ----------
         b : bool or 'line'
@@ -3268,11 +3242,9 @@ def set_xticklabels(self, labels, fontdict=None, minor=False, **kwargs):
         """
         Set the x-tick labels with list of string labels.
 
-        .. ACCEPTS: list of string labels
-
         Parameters
         ----------
-        labels : list of str
+        labels : List[str]
             List of string labels.
 
         fontdict : dict, optional
@@ -3605,11 +3577,9 @@ def set_yticklabels(self, labels, fontdict=None, minor=False, **kwargs):
         """
         Set the y-tick labels with list of strings labels.
 
-        .. ACCEPTS: list of string labels
-
         Parameters
         ----------
-        labels : list of str
+        labels : List[str]
             list of string labels
 
         fontdict : dict, optional
@@ -3747,8 +3717,6 @@ def set_navigate(self, b):
         """
         Set whether the axes responds to navigation toolbar commands
 
-        .. ACCEPTS: bool
-
         Parameters
         ----------
         b : bool
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -262,10 +262,12 @@ def test_None_zorder():
     ("ACCEPTS: [ '-' | '--' | '-.' ]", "[ '-' | '--' | '-.' ] "),
     ('ACCEPTS: Some description.', 'Some description. '),
     ('.. ACCEPTS: Some description.', 'Some description. '),
+    ('arg : int', 'int'),
+    ('arg : int\nACCEPTS: Something else.', 'Something else. '),
 ])
 def test_artist_inspector_get_valid_values(accept_clause, expected):
     class TestArtist(martist.Artist):
-        def set_f(self):
+        def set_f(self, arg):
             pass
 
     TestArtist.set_f.__doc__ = """
