DOC: update the pandas.DataFrame.plot.bar docsctring

[miquelcamprodon]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
#################### Docstring (pandas.DataFrame.plot.bar)  ####################
################################################################################

Vertical bar plot.

A bar plot is a plot that presents categorical data with
rectangular bars with lengths proportional to the values that they
represent. A bar plot shows comparisons among discrete categories. One
axis of the plot shows the specific categories being compared, and the
other axis represents a measured value.

Parameters
----------
x : label or position, default None
    Allows plotting of one column versus another.
y : label or position, default None
    Allows plotting of one column versus another.
**kwds : optional
    Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them

Examples
--------

Basic plot

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]})
    >>> ax = df.plot.bar(x='lab',y='val')

Plot a whole dataframe to a bar plot

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...                    'lifespan': lifespan}, index=index)
    >>> ax = df.plot.bar()

Plot a column of the dataframe to a bar plot

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...                    'lifespan': lifespan}, index=index)
    >>> ax = df.plot.bar(y='speed')

Plot only selected categories for the dataframe

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...          'lifespan': lifespan}, index=index)
    >>> ax = df.plot.bar(x='lifespan')

See Also
--------
pandas.DataFrame.plot.barh : Horizontal bar plot.
pandas.DataFrame.plot : Make plots of DataFrame using matplotlib.
matplotlib.pyplot.bar : Make a bar plot.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Small issue with **kwds docstring

[emilio-molina]

In our case it worked with kwds instead of **kwds.
https://github.com/pandas-dev/pandas/pull/20152/files#diff-2b118bda866f3d626ceb6b529c62cd1aR1977

[liopic]

The empty line here is not necessary.

[jorisvandenbossche]

Thanks for the PR, looking very good!
Added a few comments.

In the meantime, there have already been merged some related plotting PRs, so you will have to update with master:

git checkout bardoc
git fetch upstream
git merge upstream/master

should do the trick (but in the last step it might be needed to resolve conflicts)

[jorisvandenbossche]

You don't need to redefine the dataframe here, it still knows it from the previous example

(and same below)

[jorisvandenbossche]

Can you specify what happens if it is not specified?

[jorisvandenbossche]

the 'optional' is actually better in this case than ', default None' (but it is a gray area in the docstring guide)

[jorisvandenbossche]

Can you rephrase this as Additional keyword arguments are documented in meth:`pandas.DataFrame.plot` ?

[codecov]

Codecov Report

Merging #20158 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #20158   +/-   ##
=======================================
  Coverage   91.72%   91.72%           
=======================================
  Files         150      150           
  Lines       49165    49165           
=======================================
  Hits        45099    45099           
  Misses       4066     4066

Flag	Coverage Δ
#multiple	90.11% <ø> (ø)	⬆️
#single	41.86% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/plotting/_core.py	82.27% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 31afaf8...18fc6e2. Read the comment docs.

[miquelcamprodon]

Does it look good now?

[TomAugspurger]

Added a subplots example.

[jorisvandenbossche]

Thanks for the PR!
Welcome to check in a few hours if everything looks OK at http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.plot.bar.html#pandas.DataFrame.plot.bar