DOC: enable matplotlib plot_directive to include figures in docstrings
State: closed

This adds the matplotlib.sphinxext.plot_directive as extension to conf.py, and added a small example in the `Series.plot.line` docstring

Labels:
name: Docs

Comments:
Documentation on this is here: https://matplotlib.org/devdocs/devel/plot_directive.html

Example how it looks like for the simple things I added:

![screenshot from 2018-03-06 16-26-45](https://user-images.githubusercontent.com/1020496/37040931-3e9e33a2-215b-11e8-902d-8b3e0d799e8b.png)

cc @datapythonista I think this will be useful for the plotting docstrings
That's really cool, I think it'll make a big difference.

@dukebody, you've been working on the plot docstring, any thought based on what you did?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20015?src=pr&el=h1) Report
> Merging [#20015](https://codecov.io/gh/pandas-dev/pandas/pull/20015?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0ca77b3541ff67ca95a324de0caf60e727a835d8?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/20015/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&height=150&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/20015?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #20015   +/-   ##
=======================================
  Coverage   91.67%   91.67%           
=======================================
  Files         150      150           
  Lines       49096    49096           
=======================================
  Hits        45007    45007           
  Misses       4089     4089
```

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

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

------

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

cc @TomAugspurger looking OK?
@datapythonista We probably want to mention in the documentation for docs that, if I'm not mistaken, one of these blocks is needed everytime we want to output a figure. Hence the `close-fig` context.

Please merge this before the sprint on Saturday if possible, since it can be a real game changer for documenting plot-producing methods, as mentioned by @datapythonista .
going to merge shortly. @dukebody can you make an issue for followups to this that are needed (e.g. add how-to in the doc)
thanks!