DOC Use plot.<kind> instead of plot(kind=<kind>) GH11043
State: closed

closes #11043 

I modified the visualization documentation to use plot.<kind> instead of plot(kind=<kind>) in the examples as explained by [issue 11043](https://github.com/pydata/pandas/issues/11043).


Labels:
name: Docs
name: Visualization
description: plotting

Comments:
Thanks for putting this together! Looks pretty good to me, modulo a few nit-picks.

can we leave a small example that uses the old syntax (and maybe a note about the usefulness of having the accessor).

any comments @jorisvandenbossche @shoyer @sinhrks 

@Moisan can you squash

ok I see that we are adding `versionadded` tags for the API change in 0.17.0, but IIRC that is at the top of the docs?

but its nice to see when the method is added, so reversing some of my comments from above :)

let's leave the original version added tags (but show them with `.plot.*` rather than `.plot(kind=....)`

I know a bit of a a misnomer here, but it is overall much cleaner i think.

I am personally a bit hesitant to change this in the full plotting docs, because it is a reality that a lot of people are not using the latest pandas. Seeing these docs will lead to errors for them and potential confusion. 
(this is of course also true for other new things in the docs, but most of the time it are not full pages) 
Keeping the original syntax (`kind=''`) in the main examples on this pages would ensure the docs pages it more cross-version compatible.

How about change the actual examples and put a `::note` right above (each one)? , this encourages change, but provides the original in an easy way?

So we would let the original examples in a `::note` or would we add a few sentences about the fact that before 0.17.0 one should use `kind=''`? 

In short, what do I need to do exactly to make it in the release?

@jorisvandenbossche @shoyer what are thoughts here?

@shoyer thoughts here

I think we should update the docs to use the new syntax. It's not hard to find old versions of docs on Google, and this really is a cleaner way to do things.

sounds good to me. @Moisan let's do that (you can still leave the versionadded tags for when that actual graphing feature came into pandas I guess).

but don't add tags for the overall syntax change. I think their is already a note about that at the top anyhow.

@Moisan can you update

I thought my last commit fixed these points. Is there something I missed?

@shoyer can you review

@jorisvandenbossche @shoyer @TomAugspurger 

lgtm

@jorisvandenbossche are you OK with this? We have the old version of the docs linked on the main page, and the error should be pretty discoverable since we have the versionadded tag right before discussing the `.plot.kind` way. I'm +1

@jorisvandenbossche ?

thanks @Moisan 

docs will be built in a few hours, pls review: http://pandas-docs.github.io/pandas-docs-travis/

and if necessary issue a follow up

I reviewed the updated docs and everything seems fine. :+1: 

I also looked at the docs, and I think there is one minor thing that can be improved: the refs to the plotting methods. 
To illustrate, the docs say now in the bar plots section: _"Calling a DataFrame’s bar() method produces a multiple bar plot:"_ (from the code `Calling a DataFrame's :meth:`~DataFrame.plot.bar` method produces a multiple`). So the rendered version implies that there is a `bar()` method on DataFrame (because the `DataFrame.plot` part is left out by sphinx), which is of course not the case.

Possible solution is to leave out the `~`:  `Calling a DataFrame's :meth:`DataFrame.plot.bar` method ...` would give _"Calling a DataFrame’s `DataFrame.plot.bar()` method"_ (but it can then be rephrased a bit to not have the double DataFrame). 
Alternative solution is to provide the text that sphinx should display: `Calling a DataFrame's :meth:`plot.bar() <DataFrame.plot.bar>` method ...` would give _"Calling a DataFrame’s `plot.bar()` method"_  

@Moisan Would you be interested in a follow-up PR?

On a closer look, the example I gave is actually the only occurence of that problem :-) 
For all the rest you already used the 'absolute' reference without `~`!

I changed this one occurence in another PR: https://github.com/pydata/pandas/pull/12326

Thanks for the feedback!