[WIP] DOC Fixes pandas-dev#8447 added examples

Author: mabelvj

pandas/plotting/_core.py

@@ -1935,9 +1935,16 @@ def plot_series(data, kind='line', ax=None,                    # Series unique
 
 
 _shared_docs['boxplot'] = """
-    Make a box plot from DataFrame column optionally grouped by some columns or
-    other inputs
-
+    Make a box-and-whisker plot from DataFrame column optionally grouped by some columns 
+    or other inputs. The box extends from the Q1 to Q3 quartile values of the data, 
+    with a line at the median (Q2). The whiskers extend from the edges of 
+    box to show the range of the data. 
+    Flier points (outliers) are those past the end of the whiskers.
+    The position of the whiskers is set by default to 1.5 IQR (whis=1.5)
+    from the edge of the box.
+    `
+    For further details see `boxplot <https://en.wikipedia.org/wiki/Box_plot>`__
+    
     Parameters
     ----------
     data : the pandas object holding the data
@@ -1958,29 +1965,53 @@ def plot_series(data, kind='line', ax=None,                    # Series unique
         'dict' returns a dictionary whose values are the matplotlib
         Lines of the boxplot;
         'both' returns a namedtuple with the axes and dict.
-
         When grouping with ``by``, a Series mapping columns to ``return_type``
         is returned, unless ``return_type`` is None, in which case a NumPy
         array of axes is returned with the same shape as ``layout``.
         See the prose documentation for more.
-
     `**kwds` : Keyword Arguments
         All other plotting keyword arguments to be passed to
-        matplotlib's boxplot function
-
+        matplotlib's `boxplot <https://matplotlib.org/api/
+        _as_gen/matplotlib.pyplot.boxplot.html>`
+        function.
     Returns
     -------
     lines : dict
     ax : matplotlib Axes
     (ax, lines): namedtuple
-
     Notes
     -----
     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.
-    """
 
+    >>> df = pd.DataFrame({u'stratifying_var': np.random.uniform(0, 100, 20),
+                   u'price': np.random.normal(100, 5, 20),
+                   u'demand': np.random.normal(100, 10, 20)})
+
+    >>> df[u'quartiles'] = pd.qcut(df[u'stratifying_var'], 4,
+                           labels=[u'0-25%', u'25-50%', u'50-75%', u'75-100%'])
+
+    >>> df
+
+    To plot the boxplot of the `demand` just put:
+
+    >>> df.boxplot(column=u'demand', by=u'quartiles')
+
+    Use `grid=False` to hide the grid:
+
+    >>> df.boxplot(column=u'demand', by=u'quartiles',grid=False)
+
+    Optionally, the layout can be changed by setting `layout=(rows, cols)`:
+
+    >>> df.boxplot(column=[u'price',u'demand'], by=u'quartiles', layout=(1,2),
+                   figsize=(8,5))
+
+
+    >>> df.boxplot(column=[u'price',u'demand'], by=u'quartiles', layout=(2,1),
+                   figsize=(5,8))
+
+    """
 
 @Appender(_shared_docs['boxplot'] % _shared_doc_kwargs)
 def boxplot(data, column=None, by=None, ax=None, fontsize=None,