DOC: update the pandas.DataFrame.plot.area docstring
State: closed

- [x] PR title is "DOC: update the pandas.DataFrame.plot.area docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py pandas.DataFrame.plot.area`
- [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.plot.area`
- [x] It has been proofread on language by another sprint participant

```
################################################################################
#################### Docstring (pandas.DataFrame.plot.area) ####################
################################################################################

Draw an area plot of the input series using matplotlib.

An area plot displays graphically quantitative data.
This function wraps the matplotlib area function.

Parameters
----------
x : label or position, optional
    Coordinates for X point.
y : label or position, optional
    Coordinates for Y point.
kwds : optional
    Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.

Returns
-------
matplotlib.AxesSubplot or numpy.ndarray
    Area plot generated.

See Also
--------
pandas.DataFrame.plot : Draw a plot using matplotlib.

Examples
--------
.. plot::
    :context: close-figs

    This example draws an area plot based on the length and width of
    some animals, displayed in three bins

    >>> df = pd.DataFrame({
    ...     'sales': [3, 2, 3, 9, 10, 6],
    ...     'visits': [20, 42, 28, 62, 81, 50],
    ... })
    >>> area = df.plot.area()

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.plot.area" correct. :)
```


Labels:
name: Docs

Comments:
Can you post a screenshot of the rendered HTML? It will help reviewing without having to check out your branch and compiling it.
Is there anything we can do to help finishing the work on this PR?
I'll update the PR later this week, just need some time :+1: 
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20170?src=pr&el=h1) Report
> Merging [#20170](https://codecov.io/gh/pandas-dev/pandas/pull/20170?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d7b408e06955b66114cd34846047554441d394e1?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

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

```diff
@@           Coverage Diff           @@
##           master   #20170   +/-   ##
=======================================
  Coverage   92.07%   92.07%           
=======================================
  Files         169      169           
  Lines       50683    50683           
=======================================
  Hits        46666    46666           
  Misses       4017     4017
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.48% <ø> (ø)` | :arrow_up: |
| #single | `42.34% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20170?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20170/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `83.48% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20170?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/20170?src=pr&el=footer). Last update [d7b408e...3f02fe7](https://codecov.io/gh/pandas-dev/pandas/pull/20170?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Fixed most of the suggestions, except for:
- writing `**kwds` instead of `kwds`. That would break the validation.
- more/better examples: I ask for inspiration :)

Also, a screenshot of the example:
![image](https://user-images.githubusercontent.com/353447/37460194-ccceaa6c-284a-11e8-8a43-863b4a1131e1.png)

> writing **kwds instead of kwds. That would break the validation.

You can ignore this, `**kwargs` is correct, the script is incorrect :)
http://pandas.pydata.org/pandas-docs/stable/visualization.html#area-plot has an example. The same thing with a datetimeidnex from `pd.date_range` would be nice (maybe a bit wider of an aspect ratio).
Hi,

I've updated with all the proposals, and rebased.

Screenshots of the rendered example section:
![image](https://user-images.githubusercontent.com/353447/37930583-7eae75a4-3143-11e8-8319-ec24aac75a34.png)
![image](https://user-images.githubusercontent.com/353447/37930595-856efb52-3143-11e8-8a47-3f55c47f19e4.png)
![image](https://user-images.githubusercontent.com/353447/37930606-8c1a49f2-3143-11e8-9cc4-55f39b1627df.png)
![image](https://user-images.githubusercontent.com/353447/37930619-913c5182-3143-11e8-8f91-ec5f1ec82ca0.png)
![image](https://user-images.githubusercontent.com/353447/37930629-97613dd4-3143-11e8-9f39-e1c7ec03d63d.png)

It looks much better :) Thanks for the feedback!
Ping @kynan @jorisvandenbossche @TomAugspurger @dukebody 

Feel free to keep reviewing, or do the merge :)
@DZPM Thanks for the reminder! 
Can you add a datetime index to the example frame? See https://github.com/pandas-dev/pandas/pull/20170#issuecomment-373364136
@DZPM can you please update this PR based on the previous feedback
Sure, will do. (Sorry, I've been busy and the PR slipped my mind...)
Done. Added the changes in a new commit, and rebased.
Changes done, and rebased. Hope it's ok!
LGTM, thanks!

If you want, check the doc build when it finishes (probably a few hours).