DOC: Use shared docstring

Author: TomAugspurger

doc/source/groupby.rst

@@ -925,7 +925,7 @@ the values in column 1 where the group is "B" are 3 higher on average.
 
 We can easily visualize this with a boxplot:
 
-..ipython:: python
+.. ipython:: python
 
    @savefig groupby_boxplot.png
    bp = df.groupby('g').boxplot()
@@ -938,7 +938,8 @@ See the :ref:`visualization documentation<visualization.box>` for more.
 .. warning::
 
   For historical reasons, ``df.groupby("g").boxplot()`` is not equivalent
-  to ``df.boxplot(by="g")``. See :ref:`here<visualization.box.return>`.
+  to ``df.boxplot(by="g")``. See :ref:`here<visualization.box.return>` for
+  an explanation.
 
 Examples
 --------

doc/source/release.rst

@@ -262,7 +262,7 @@ Deprecations
   default output is unchanged.
 
 - The default return type of :func:`boxplot` will change from a dict to a matpltolib Axes
-  in a future release. You can use the future behavior now by passing ``return_type='dict'``
+  in a future release. You can use the future behavior now by passing ``return_type='axes'``
   to boxplot.
 
 Prior Version Deprecations/Changes

doc/source/v0.14.0.txt

@@ -579,7 +579,7 @@ Deprecations
   default output is unchanged.
 
 - The default return type of :func:`boxplot` will change from a dict to a matpltolib Axes
-  in a future release. You can use the future behavior now by passing ``return_type='dict'``
+  in a future release. You can use the future behavior now by passing ``return_type='axes'``
   to boxplot.
 
 .. _whatsnew_0140.enhancements:

doc/source/visualization.rst

@@ -331,14 +331,15 @@ DataFrame.
    df_box['g'] = np.random.choice(['A', 'B'], size=50)
    df_box.loc[df_box['g'] == 'B', 1] += 3
 
-..ipython:: python
+   @savefig boxplot_groupby.png
+   bp = df_box.boxplot(by='g')
 
-   @savefig(boxplot_groupby.png)
-   df_box.boxplot(by='g')
+Compare to:
 
-   @savefig groupby_boxplot_vis.png
-   df_box.groupby('g').boxplot()
+.. ipython:: python
 
+   @savefig groupby_boxplot_vis.png
+   bp = df_box.groupby('g').boxplot()
 
 .. _visualization.area_plot:
 

pandas/core/frame.py

@@ -4856,48 +4856,15 @@ def _put_str(s, space):
 DataFrame.hist = gfx.hist_frame
 
 
+@Appender(_shared_docs['boxplot'] % _shared_doc_kwargs)
 def boxplot(self, column=None, by=None, ax=None, fontsize=None,
             rot=0, grid=True, figsize=None, layout=None, return_type=None,
             **kwds):
-    """
-    Make a box plot from DataFrame column/columns optionally grouped
-    (stratified) by one or more columns
-
-    Parameters
-    ----------
-    data : DataFrame
-    column : column names or list of names, or vector
-        Can be any valid input to groupby
-    by : string or sequence
-        Column in the DataFrame to group by
-    ax : matplotlib axis object, default None
-    fontsize : int or string
-    rot : int, default None
-        Rotation for ticks
-    grid : boolean, default None (matlab style default)
-        Axis grid lines
-    layout : tuple (optional)
-        (rows, columns) for the layout of the plot
-    return_type : bool, default False
-        Whether to return a dict whose values are the lines of the boxplot
-    kwds : other plotting keyword arguments to be passed to matplotlib boxplot
-           function
-
-    Returns
-    -------
-    ax : matplotlib.axes.AxesSubplot
-    lines : dict (optional)
-
-    Notes
-    -----
-    Use ``return_dict=True`` when you want to modify the appearance
-    of the lines. In this case a named tuple is returned.
-    """
     import pandas.tools.plotting as plots
     import matplotlib.pyplot as plt
     ax = plots.boxplot(self, column=column, by=by, ax=ax,
                        fontsize=fontsize, grid=grid, rot=rot,
-                       figsize=figsize, layout=layout, return_dict=return_dict,
+                       figsize=figsize, layout=layout, return_type=return_type,
                        **kwds)
     plt.draw_if_interactive()
     return ax

pandas/tools/plotting.py

@@ -11,6 +11,7 @@
 
 from pandas.util.decorators import cache_readonly, deprecate_kwarg
 import pandas.core.common as com
+from pandas.core.generic import _shared_docs, _shared_doc_kwargs
 from pandas.core.index import MultiIndex
 from pandas.core.series import Series, remove_na
 from pandas.tseries.index import DatetimeIndex
@@ -19,6 +20,7 @@
 from pandas.tseries.offsets import DateOffset
 from pandas.compat import range, lrange, lmap, map, zip, string_types
 import pandas.compat as compat
+from pandas.util.decorators import Appender
 
 try:  # mpl optional
     import pandas.tseries.converter as conv
@@ -2258,16 +2260,13 @@ def plot_series(series, label=None, kind='line', use_index=True, rot=None,
     return plot_obj.axes[0]
 
 
-def boxplot(data, column=None, by=None, ax=None, fontsize=None,
-            rot=0, grid=True, figsize=None, layout=None, return_type=None,
-            **kwds):
-    """
+_shared_docs['boxplot'] = """
     Make a box plot from DataFrame column optionally grouped by some columns or
     other inputs
 
     Parameters
     ----------
-    data : DataFrame or Series
+    data : the pandas object holding the data
     column : column name or list of names, or vector
         Can be any valid input to groupby
     by : string or sequence
@@ -2299,7 +2298,7 @@ def boxplot(data, column=None, by=None, ax=None, fontsize=None,
 
     Notes
     -----
-    Use ``return_dict=True`` when you want to tweak the appearance
+    Use ``return_type='dict'`` when you want to tweak the appearance
     of the lines after plotting. In this case a dict containing the Lines
     making up the boxes, caps, fliers, medians, and whiskers is returned.
     """
@@ -2315,6 +2314,7 @@ def boxplot(data, column=None, by=None, ax=None, fontsize=None,
     if return_type not in valid_types:
         raise ValueError("return_type")
 
+
     from pandas import Series, DataFrame
     if isinstance(data, Series):
         data = DataFrame({'x': data})