DOC: update pandas.DataFrame.boxplot docstring. Fixes #8847 
State: closed

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py pandas.DataFrame.boxplot`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single pandas.DataFrame.boxplot`
- [x] It has been proofread on language by another sprint participant


```
################################################################################
##################### Docstring (pandas.DataFrame.boxplot) #####################
################################################################################

Make a box plot from DataFrame columns.

Make a box-and-whisker plot from DataFrame columns optionally grouped
by some other columns. A box plot is a method for graphically depicting
groups of numerical data through their quartiles.
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. The position of the whiskers
is set by default to 1.5*IQR (IQR = Q3 - Q1) from the edges of the box.
Outlier points are those past the end of the whiskers.

For further details see
Wikipedia's entry for `boxplot <https://en.wikipedia.org/wiki/Box_plot>`_.

Parameters
----------
column : str or list of str, optional
    Column name or list of names, or vector.
    Can be any valid input to groupby.
by : str or array-like
    Column in the DataFrame to groupby.
ax : object of class matplotlib.axes.Axes, default `None`
    The matplotlib axes to be used by boxplot.
fontsize : float or str
    Tick label font size in points or as a string (e.g., ‘large’)
    (see `matplotlib.axes.Axes.tick_params
    <https://matplotlib.org/api/_as_gen/
    matplotlib.axes.Axes.tick_params.html>`_).
rot : int or float, default 0
    The rotation angle of labels (in degrees)
    with respect to the screen coordinate sytem.
grid : boolean, default `True`
    Setting this to True will show the grid.
figsize : A tuple (width, height) in inches
    The size of the figure to create in matplotlib.
layout : tuple (rows, columns) (optional)
    For example, (3, 5) will display the subplots
    using 3 columns and 5 rows, starting from the top-left.
return_type : {None, 'axes', 'dict', 'both'}, default 'axes'
    The kind of object to return. The default is ``axes``.

    * 'axes' returns the matplotlib axes the boxplot is drawn on.
    * '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 (i.e.
      ``df.boxplot(column=['Col1','Col2'], by='var',return_type='axes')``
      may return ``Series([AxesSubplot(..),AxesSubplot(..)],
      index=['Col1','Col2'])``).

      If ``return_type`` is `None`, a NumPy array
      of axes with the same shape as ``layout`` is returned
      (i.e. ``df.boxplot(column=['Col1','Col2'],
      by='var',return_type=None)`` may return a
      ``array([<matplotlib.axes._subplots.AxesSubplot object at ..>,
      <matplotlib.axes._subplots.AxesSubplot object at ..>],
      dtype=object)``).
**kwds : Keyword Arguments (optional)
    All other plotting keyword arguments to be passed to
    `matplotlib.pyplot.boxplot <https://matplotlib.org/api/_as_gen/
    matplotlib.pyplot.boxplot.html#matplotlib.pyplot.boxplot>`_.

Returns
-------
result:
    Options:

    * ax : object of class
      matplotlib.axes.Axes (for ``return_type='axes'``)
    * lines : dict (for ``return_type='dict'``)
    * (ax, lines): namedtuple (for ``return_type='both'``)
    * :class:`~pandas.Series` (for ``return_type != None``
      and data grouped with ``by``)
    * :class:`~numpy.array` (for ``return_type=None``
      and data grouped with ``by``)

See Also
--------
matplotlib.pyplot.boxplot: Make a box and whisker plot.
matplotlib.pyplot.hist: Make a hsitogram.

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.

Examples
--------

Boxplots can be created for every column in the dataframe
by ``df.boxplot()`` or indicating the columns to be used:

.. plot::
    :context: close-figs

    >>> np.random.seed(1234)
    >>> df = pd.DataFrame(np.random.rand(10,4),
    ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
    >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])

Boxplots of variables distributions grouped by a third variable values
can be created using the option ``by``. For instance:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,2), columns=['Col1', 'Col2'] )
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X')

A list of strings (i.e. ``['X','Y']``) containing can be passed to boxplot
in order to group the data by combination of the variables in the x-axis:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,3),
    ...                   columns=['Col1', 'Col2', 'Col3'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> df['Y'] = pd.Series(['A','B','A','B','A','B','A','B','A','B'])
    >>> boxplot = df.boxplot(column=['Col1','Col2'], by=['X','Y'])

The layout of boxplot can be adjusted giving a tuple to ``layout``:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,2), columns=['Col1', 'Col2'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X', layout=(2,1))

Additional formatting can be done to the boxplot, like suppressing the grid
(``grid=False``), rotating the labels in the x-axis (i.e. ``rot=45``)
or changing the fontsize (i.e. ``fontsize=15``):

.. plot::
    :context: close-figs

    >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}
```
<img width="507" alt="captura de pantalla 2018-03-12 a las 0 51 51" src="https://user-images.githubusercontent.com/15342068/37260125-ab870588-258f-11e8-837d-80497fb392eb.png">
<img width="496" alt="captura de pantalla 2018-03-12 a las 0 52 04" src="https://user-images.githubusercontent.com/15342068/37260124-ab4d8d3a-258f-11e8-9dd9-9c5c7dca16cf.png">
<img width="492" alt="captura de pantalla 2018-03-12 a las 0 52 12" src="https://user-images.githubusercontent.com/15342068/37260123-ab316ed4-258f-11e8-863a-2c9e8fe1e67d.png">
<img width="494" alt="captura de pantalla 2018-03-12 a las 0 52 18" src="https://user-images.githubusercontent.com/15342068/37260122-ab1480e4-258f-11e8-9b2b-debe1c7355da.png">

@EliosMolina

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=h1) Report
> Merging [#20152](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/4efb39f01f5880122fa38d91e12d217ef70fad9e?src=pr&el=desc) will **increase** coverage by `0.02%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20152/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&height=150&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20152      +/-   ##
==========================================
+ Coverage   91.82%   91.84%   +0.02%     
==========================================
  Files         152      152              
  Lines       49255    49255              
==========================================
+ Hits        45226    45240      +14     
+ Misses       4029     4015      -14
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.23% <ø> (+0.02%)` | :arrow_up: |
| #single | `41.9% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20152/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.5% <ø> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20152/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `84.73% <0%> (+0.2%)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20152/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `66.81% <0%> (+1.73%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=footer). Last update [4efb39f...39bb166](https://codecov.io/gh/pandas-dev/pandas/pull/20152?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Updated the documentation and the first comment of the PR with the new screenshots and output of the validation test.
@mabelvj can you go over the comments in the review? There are some of them that need to be addressed before we can merge this.
Yes, I was reviewing them all before making a commit. Had some doubts with the examples for `return_type` part. 
You accidentally added some binary files to your last commit.
Just to verify, the validate_docstring script passes with your latest (aside from `**kwargs`)?
@TomAugspurger, no errors aside from **kwds

```
################################################################################
##################### Docstring (pandas.DataFrame.boxplot) #####################
################################################################################

Make a box plot from DataFrame columns.

Make a box-and-whisker plot from DataFrame columns, optionally grouped
by some other columns. A box plot is a method for graphically depicting
groups of numerical data through their quartiles.
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. The position of the whiskers
is set by default to `1.5 * IQR (IQR = Q3 - Q1)` from the edges of the box.
Outlier points are those past the end of the whiskers.

For further details see
Wikipedia's entry for `boxplot <https://en.wikipedia.org/wiki/Box_plot>`_.

Parameters
----------
column : str or list of str, optional
    Column name or list of names, or vector.
    Can be any valid input to :meth:`pandas.DataFrame.groupby`.
by : str or array-like, optional
    Column in the DataFrame to :meth:`pandas.DataFrame.groupby`.
    One box-plot will be done per value of columns in `by`.
ax : object of class matplotlib.axes.Axes, optional
    The matplotlib axes to be used by boxplot.
fontsize : float or str
    Tick label font size in points or as a string (e.g., `large`).
rot : int or float, default 0
    The rotation angle of labels (in degrees)
    with respect to the screen coordinate sytem.
grid : boolean, default True
    Setting this to True will show the grid.
figsize : A tuple (width, height) in inches
    The size of the figure to create in matplotlib.
layout : tuple (rows, columns), optional
    For example, (3, 5) will display the subplots
    using 3 columns and 5 rows, starting from the top-left.
return_type : {'axes', 'dict', 'both'} or None, default 'axes'
    The kind of object to return. The default is ``axes``.

    * 'axes' returns the matplotlib axes the boxplot is drawn on.
    * '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.

      If ``return_type`` is `None`, a NumPy array
      of axes with the same shape as ``layout`` is returned.
**kwds : Keyword Arguments, optional
    All other plotting keyword arguments to be passed to
    :func:`matplotlib.pyplot.boxplot`.

Returns
-------
result :

    The return type depends on the `return_type` parameter:

    * 'axes' : object of class matplotlib.axes.Axes
    * 'dict' : dict of matplotlib.lines.Line2D objects
    * 'both' : a nametuple with strucure (ax, lines)

    For data grouped with ``by``:

    * :class:`~pandas.Series`
    * :class:`~numpy.array` (for ``return_type = None``)

See Also
--------
Series.plot.hist: Make a histogram.
matplotlib.pyplot.boxplot : Matplotlib equivalent plot.

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.

Examples
--------

Boxplots can be created for every column in the dataframe
by ``df.boxplot()`` or indicating the columns to be used:

.. plot::
    :context: close-figs

    >>> np.random.seed(1234)
    >>> df = pd.DataFrame(np.random.randn(10,4),
    ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
    >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])

Boxplots of variables distributions grouped by the values of a third
variable can be created using the option ``by``. For instance:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,2), columns=['Col1', 'Col2'] )
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X')

A list of strings (i.e. ``['X','Y']``) can be passed to boxplot
in order to group the data by combination of the variables in the x-axis:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,3),
    ...                   columns=['Col1', 'Col2', 'Col3'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> df['Y'] = pd.Series(['A','B','A','B','A','B','A','B','A','B'])
    >>> boxplot = df.boxplot(column=['Col1','Col2'], by=['X','Y'])

The layout of boxplot can be adjusted giving a tuple to ``layout``:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,2), columns=['Col1', 'Col2'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X', layout=(2,1))

Additional formatting can be done to the boxplot, like suppressing the grid
(``grid=False``), rotating the labels in the x-axis (i.e. ``rot=45``)
or changing the fontsize (i.e. ``fontsize=15``):

.. plot::
    :context: close-figs

    >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)

The parameter ``return_type`` can be used to select the type of element
returned by `boxplot`.  When ``return_type='axes'`` is selected,
the matplotlib axes on which the boxplot is drawn are returned:

    >>> boxplot = df.boxplot(column=['Col1','Col2'], return_type='axes')
    >>> type(boxplot)
    <class 'matplotlib.axes._subplots.AxesSubplot'>

When grouping with ``by``, a Series mapping columns to ``return_type``
is returned:

    >>> boxplot = df.boxplot(column=['Col1','Col2'], by='X',
    ...                      return_type='axes')
    >>> type(boxplot)
    <class 'pandas.core.series.Series'>

If ``return_type`` is `None`, a NumPy array of axes with the same shape
as ``layout`` is returned:

    >>> boxplot =  df.boxplot(column=['Col1','Col2'], by='X',
    ...                       return_type=None)
    >>> type(boxplot)
    <class 'numpy.ndarray'>

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}

```
Result:

<img width="615" alt="captura de pantalla 2018-04-02 a las 15 34 08" src="https://user-images.githubusercontent.com/15342068/38198071-82be7a16-368b-11e8-935f-acb63011c33e.png">
<img width="618" alt="captura de pantalla 2018-04-02 a las 15 34 24" src="https://user-images.githubusercontent.com/15342068/38198069-8298747e-368b-11e8-8a03-f9ec4b698d47.png">
<img width="604" alt="captura de pantalla 2018-04-02 a las 15 38 51" src="https://user-images.githubusercontent.com/15342068/38198182-fbca6fa0-368b-11e8-86f4-78311d468b02.png">
<img width="626" alt="captura de pantalla 2018-04-02 a las 15 34 43" src="https://user-images.githubusercontent.com/15342068/38198066-824f6eb4-368b-11e8-9f19-2e4e08d9b5ee.png">
<img width="607" alt="captura de pantalla 2018-04-02 a las 15 34 48" src="https://user-images.githubusercontent.com/15342068/38198065-82284f96-368b-11e8-995c-682fd42ec9a8.png">
@mabelvj Thanks a lot !!
Thank you! I've learned a lot!