Merge pull request #11542 from fredrik-1/doc_thetagrids

NelleV · web-flow · commit f4127b12ad5b · 2018-06-30T13:17:44.000-07:00
Documentation polar grids
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
@@ -1221,27 +1221,39 @@ def set_rscale(self, *args, **kwargs):
     def set_rticks(self, *args, **kwargs):
         return Axes.set_yticks(self, *args, **kwargs)
 
-    @docstring.dedent_interpd
     def set_thetagrids(self, angles, labels=None, fmt=None, **kwargs):
         """
-        Set the angles at which to place the theta grids (these
-        gridlines are equal along the theta dimension).  *angles* is in
-        degrees.
+        Set the theta gridlines in a polar plot.
 
-        *labels*, if not None, is a ``len(angles)`` list of strings of
-        the labels to use at each angle.
-
-        If *labels* is None, the labels will be ``fmt %% angle``
-
-        Return value is a list of tuples (*line*, *label*), where
-        *line* is :class:`~matplotlib.lines.Line2D` instances and the
-        *label* is :class:`~matplotlib.text.Text` instances.
+        Parameters
+        ----------
+        angles : tuple with floats, degrees
+            The angles of the theta gridlines.
 
-        kwargs are optional text properties for the labels:
+        labels : tuple with strings or None
+            The labels to use at each theta gridline. The
+            `.projections.polar.ThetaFormatter` will be used if None.
 
-        %(Text)s
+        fmt : str or None
+            Format string used in `matplotlib.ticker.FormatStrFormatter`.
+            For example '%f'. Note that the angle that is used is in
+            radians.
 
-        ACCEPTS: sequence of floats
+        Returns
+        -------
+        lines, labels : list of `.lines.Line2D`, list of `.text.Text`
+            *lines* are the theta gridlines and *labels* are the tick labels.
+
+        Other Parameters
+        ----------------
+        **kwargs
+            *kwargs* are optional `~.Text` properties for the labels.
+
+        See Also
+        --------
+        .PolarAxes.set_rgrids
+        .Axis.get_gridlines
+        .Axis.get_ticklabels
         """
 
         # Make sure we take into account unitized data
@@ -1256,29 +1268,42 @@ def set_thetagrids(self, angles, labels=None, fmt=None, **kwargs):
             t.update(kwargs)
         return self.xaxis.get_ticklines(), self.xaxis.get_ticklabels()
 
-    @docstring.dedent_interpd
     def set_rgrids(self, radii, labels=None, angle=None, fmt=None,
                    **kwargs):
         """
-        Set the radial locations and labels of the *r* grids.
-
-        The labels will appear at radial distances *radii* at the
-        given *angle* in degrees.
+        Set the radial gridlines on a polar plot.
 
-        *labels*, if not None, is a ``len(radii)`` list of strings of the
-        labels to use at each radius.
-
-        If *labels* is None, the built-in formatter will be used.
+        Parameters
+        ----------
+        radii : tuple with floats
+            The radii for the radial gridlines
 
-        Return value is a list of tuples (*line*, *label*), where
-        *line* is :class:`~matplotlib.lines.Line2D` instances and the
-        *label* is :class:`~matplotlib.text.Text` instances.
+        labels : tuple with strings or None
+            The labels to use at each radial gridline. The
+            `matplotlib.ticker.ScalarFormatter` will be used if None.
 
-        kwargs are optional text properties for the labels:
+        angle : float
+            The angular position of the radius labels in degrees.
 
-        %(Text)s
+        fmt : str or None
+            Format string used in `matplotlib.ticker.FormatStrFormatter`.
+            For example '%f'.
 
-        ACCEPTS: sequence of floats
+        Returns
+        -------
+        lines, labels : list of `.lines.Line2D`, list of `.text.Text`
+            *lines* are the radial gridlines and *labels* are the tick labels.
+
+        Other Parameters
+        ----------------
+        **kwargs
+            *kwargs* are optional `~.Text` properties for the labels.
+
+        See Also
+        --------
+        .PolarAxes.set_thetagrids
+        .Axis.get_gridlines
+        .Axis.get_ticklabels
         """
         # Make sure we take into account unitized data
         radii = self.convert_xunits(radii)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1626,36 +1626,62 @@ def yticks(ticks=None, labels=None, **kwargs):
 
     return locs, silent_list('Text yticklabel', labels)
 
-
 def rgrids(*args, **kwargs):
     """
-    Get or set the radial gridlines on a polar plot.
+    Get or set the radial gridlines on the current polar plot.
+
+    Call signatures::
 
-    call signatures::
+     lines, labels = rgrids()
+     lines, labels = rgrids(radii, labels=None, angle=22.5, fmt=None, **kwargs)
 
-      lines, labels = rgrids()
-      lines, labels = rgrids(radii, labels=None, angle=22.5, **kwargs)
+    When called with no arguments, `.rgrids` simply returns the tuple
+    (*lines*, *labels*). When called with arguments, the labels will
+    appear at the specified radial distances and angle.
 
-    When called with no arguments, :func:`rgrid` simply returns the
-    tuple (*lines*, *labels*), where *lines* is an array of radial
-    gridlines (:class:`~matplotlib.lines.Line2D` instances) and
-    *labels* is an array of tick labels
-    (:class:`~matplotlib.text.Text` instances). When called with
-    arguments, the labels will appear at the specified radial
-    distances and angles.
+    Parameters
+    ----------
+    radii : tuple with floats
+        The radii for the radial gridlines
 
-    *labels*, if not *None*, is a len(*radii*) list of strings of the
-    labels to use at each angle.
+    labels : tuple with strings or None
+        The labels to use at each radial gridline. The
+        `matplotlib.ticker.ScalarFormatter` will be used if None.
 
-    If *labels* is None, the rformatter will be used
+    angle : float
+        The angular position of the radius labels in degrees.
 
-    Examples::
+    fmt : str or None
+        Format string used in `matplotlib.ticker.FormatStrFormatter`.
+        For example '%f'.
 
-      # set the locations of the radial gridlines and labels
+    Returns
+    -------
+    lines, labels : list of `.lines.Line2D`, list of `.text.Text`
+        *lines* are the radial gridlines and *labels* are the tick labels.
+
+    Other Parameters
+    ----------------
+    **kwargs
+        *kwargs* are optional `~.Text` properties for the labels.
+
+    Examples
+    --------
+    ::
+
+      # set the locations of the radial gridlines
       lines, labels = rgrids( (0.25, 0.5, 1.0) )
 
-      # set the locations and labels of the radial gridlines and labels
-      lines, labels = rgrids( (0.25, 0.5, 1.0), ('Tom', 'Dick', 'Harry' )
+      # set the locations and labels of the radial gridlines
+      lines, labels = rgrids( (0.25, 0.5, 1.0), ('Tom', 'Dick', 'Harry' ))
+
+    See Also
+    --------
+    .pyplot.thetagrids
+    .projections.polar.PolarAxes.set_rgrids
+    .Axis.get_gridlines
+    .Axis.get_ticklabels
+
 
     """
     ax = gca()
@@ -1670,57 +1696,62 @@ def rgrids(*args, **kwargs):
     return ( silent_list('Line2D rgridline', lines),
              silent_list('Text rgridlabel', labels) )
 
-
 def thetagrids(*args, **kwargs):
     """
-    Get or set the theta locations of the gridlines in a polar plot.
+    Get or set the theta gridlines on the current polar plot.
 
-    If no arguments are passed, return a tuple (*lines*, *labels*)
-    where *lines* is an array of radial gridlines
-    (:class:`~matplotlib.lines.Line2D` instances) and *labels* is an
-    array of tick labels (:class:`~matplotlib.text.Text` instances)::
-
-      lines, labels = thetagrids()
-
-    Otherwise the syntax is::
-
-      lines, labels = thetagrids(angles, labels=None, fmt='%d', frac = 1.1)
-
-    set the angles at which to place the theta grids (these gridlines
-    are equal along the theta dimension).
-
-    *angles* is in degrees.
+    Call signatures::
 
-    *labels*, if not *None*, is a len(angles) list of strings of the
-    labels to use at each angle.
+     lines, labels = thetagrids()
+     lines, labels = thetagrids(angles, labels=None, fmt=None, **kwargs)
 
-    If *labels* is *None*, the labels will be ``fmt%angle``.
+    When called with no arguments, `.thetagrids` simply returns the tuple
+    (*lines*, *labels*). When called with arguments, the labels will
+    appear at the specified angles.
 
-    *frac* is the fraction of the polar axes radius at which to place
-    the label (1 is the edge). e.g., 1.05 is outside the axes and 0.95
-    is inside the axes.
+    Parameters
+    ----------
+    angles : tuple with floats, degrees
+        The angles of the theta gridlines.
 
-    Return value is a list of tuples (*lines*, *labels*):
+    labels : tuple with strings or None
+        The labels to use at each radial gridline. The
+        `.projections.polar.ThetaFormatter` will be used if None.
 
-      - *lines* are :class:`~matplotlib.lines.Line2D` instances
+    fmt : str or None
+        Format string used in `matplotlib.ticker.FormatStrFormatter`.
+        For example '%f'. Note that the angle in radians will be used.
 
-      - *labels* are :class:`~matplotlib.text.Text` instances.
+    Returns
+    -------
+    lines, labels : list of `.lines.Line2D`, list of `.text.Text`
+        *lines* are the theta gridlines and *labels* are the tick labels.
 
-    Note that on input, the *labels* argument is a list of strings,
-    and on output it is a list of :class:`~matplotlib.text.Text`
-    instances.
+    Other Parameters
+    ----------------
+    **kwargs
+        *kwargs* are optional `~.Text` properties for the labels.
 
-    Examples::
+    Examples
+    --------
+    ::
 
-      # set the locations of the radial gridlines and labels
+      # set the locations of the angular gridlines
       lines, labels = thetagrids( range(45,360,90) )
 
-      # set the locations and labels of the radial gridlines and labels
+      # set the locations and labels of the angular gridlines
       lines, labels = thetagrids( range(45,360,90), ('NE', 'NW', 'SW','SE') )
+
+    See Also
+    --------
+    .pyplot.rgrids
+    .projections.polar.PolarAxes.set_thetagrids
+    .Axis.get_gridlines
+    .Axis.get_ticklabels
     """
     ax = gca()
     if not isinstance(ax, PolarAxes):
-        raise RuntimeError('rgrids only defined for polar axes')
+        raise RuntimeError('thetagrids only defined for polar axes')
     if len(args)==0:
         lines = ax.xaxis.get_ticklines()
         labels = ax.xaxis.get_ticklabels()
