Merge pull request #8371 from phobson/pie-docstring

QuLogic · dstansby · commit 5e3df6691797 · 2017-03-25T16:28:15.000Z
DOC: Clean up the pie docstring PR
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2478,92 +2478,95 @@ def pie(self, x, explode=None, labels=None, colors=None,
         Plot a pie chart.
 
         Make a pie chart of array *x*.  The fractional area of each
-        wedge is given by x/sum(x).  If sum(x) <= 1, then the values
-        of x give the fractional area directly and the array will not
-        be normalized.  The wedges are plotted counterclockwise,
-        by default starting from the x-axis.
+        wedge is given by ``x/sum(x)``.  If ``sum(x) <= 1``, then the
+        values of x give the fractional area directly and the array
+        will not be normalized.  The wedges are plotted
+        counterclockwise, by default starting from the x-axis.
 
-        Keyword arguments:
+        Parameters
+        ----------
+        x : array-like
+            The input array used to make the pie chart.
 
-          *explode*: [ *None* | len(x) sequence ]
+        explode : array-like, optional, default: None
             If not *None*, is a ``len(x)`` array which specifies the
             fraction of the radius with which to offset each wedge.
 
-          *colors*: [ *None* | color sequence ]
+        labels : list, optional, default: None
+            A sequence of strings providing the labels for each wedge
+
+        colors : array-like, optional, default: None
             A sequence of matplotlib color args through which the pie chart
             will cycle.  If `None`, will use the colors in the currently
             active cycle.
 
-          *labels*: [ *None* | len(x) sequence of strings ]
-            A sequence of strings providing the labels for each wedge
-
-          *autopct*: [ *None* | format string | format function ]
+        autopct : None (default), string, or function, optional
             If not *None*, is a string or function used to label the wedges
             with their numeric value.  The label will be placed inside the
             wedge.  If it is a format string, the label will be ``fmt%pct``.
             If it is a function, it will be called.
 
-          *pctdistance*: scalar
+        pctdistance : float, optional, default: 0.6
             The ratio between the center of each pie slice and the
             start of the text generated by *autopct*.  Ignored if
-            *autopct* is *None*; default is 0.6.
-
-          *labeldistance*: scalar
-            The radial distance at which the pie labels are drawn
+            *autopct* is *None*.
 
-          *shadow*: [ *False* | *True* ]
+        shadow : bool, optional, default: False
             Draw a shadow beneath the pie.
 
-          *startangle*: [ *None* | Offset angle ]
+        labeldistance : float, optional, default: 1.1
+            The radial distance at which the pie labels are drawn
+
+        startangle : float, optional, default: None
             If not *None*, rotates the start of the pie chart by *angle*
             degrees counterclockwise from the x-axis.
 
-          *radius*: [ *None* | scalar ]
-          The radius of the pie, if *radius* is *None* it will be set to 1.
+        radius : float, optional, default: None
+            The radius of the pie, if *radius* is *None* it will be set to 1.
 
-          *counterclock*: [ *False* | *True* ]
+        counterclock : bool, optional, default: True
             Specify fractions direction, clockwise or counterclockwise.
 
-          *wedgeprops*: [ *None* | dict of key value pairs ]
+        wedgeprops : dict, optional, default: None
             Dict of arguments passed to the wedge objects making the pie.
-            For example, you can pass in wedgeprops = { 'linewidth' : 3 }
+            For example, you can pass in``wedgeprops = {'linewidth': 3}``
             to set the width of the wedge border lines equal to 3.
             For more details, look at the doc/arguments of the wedge object.
-            By default `clip_on=False`.
+            By default ``clip_on=False``.
 
-          *textprops*: [ *None* | dict of key value pairs ]
+        textprops : dict, optional, default: None
             Dict of arguments to pass to the text objects.
 
-          *center*: [ (0,0) | sequence of 2 scalars ]
-          Center position of the chart.
+        center :  list of float, optional, default: (0, 0)
+            Center position of the chart. Takes value (0, 0) or is a
+            sequence of 2 scalars.
 
-          *frame*: [ *False* | *True* ]
-            Plot axes frame with the chart.
+        frame : bool, optional, default: False
+            Plot axes frame with the chart if true.
 
-        The pie chart will probably look best if the figure and axes are
-        square, or the Axes aspect is equal.  e.g.::
-
-          figure(figsize=(8,8))
-          ax = axes([0.1, 0.1, 0.8, 0.8])
+        Returns
+        -------
+        patches : list
+            A sequence of :class:`matplotlib.patches.Wedge` instances
 
-        or::
+        texts : list
+            A is a list of the label :class:`matplotlib.text.Text` instances.
 
-          axes(aspect=1)
+        autotexts : list
+            A is a list of :class:`~matplotlib.text.Text` instances for the
+            numeric labels. Is returned only if parameter *autopct* is
+            not *None*.
 
-        Return value:
-          If *autopct* is *None*, return the tuple (*patches*, *texts*):
+        Notes
+        -----
+        The pie chart will probably look best if the figure and axes are
+        square, or the Axes aspect is equal.
 
-            - *patches* is a sequence of
-              :class:`matplotlib.patches.Wedge` instances
+        Examples
+        --------
+        .. plot:: mpl_examples/pie_and_polar_charts/pie_demo_features.py
 
-            - *texts* is a list of the label
-              :class:`matplotlib.text.Text` instances.
 
-          If *autopct* is not *None*, return the tuple (*patches*,
-          *texts*, *autotexts*), where *patches* and *texts* are as
-          above, and *autotexts* is a list of
-          :class:`~matplotlib.text.Text` instances for the numeric
-          labels.
         """
 
         x = np.asarray(x).astype(np.float32)
@@ -2621,9 +2624,9 @@ def get_next_color():
             y += expl * math.sin(thetam)
 
             w = mpatches.Wedge((x, y), radius, 360. * min(theta1, theta2),
-                            360. * max(theta1, theta2),
-                            facecolor=get_next_color(),
-                            **wedgeprops)
+                               360. * max(theta1, theta2),
+                               facecolor=get_next_color(),
+                               **wedgeprops)
             slices.append(w)
             self.add_patch(w)
             w.set_label(label)
@@ -2674,9 +2677,9 @@ def get_next_color():
             self.set_frame_on(False)
 
             self.set_xlim((-1.25 + center[0],
-                            1.25 + center[0]))
+                           1.25 + center[0]))
             self.set_ylim((-1.25 + center[1],
-                            1.25 + center[1]))
+                           1.25 + center[1]))
             self.set_xticks([])
             self.set_yticks([])
 
