DOC: Improving docstring of pop method (#16416)

[datapythonista]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master --name-only -- '*.py' | flake8 --diff
• whatsnew entry

As discussed in gitter, it'd be nice to have more and better examples in the API documentation. I think it'd be nice to have as many examples as possible with the same DataFrame, so the users who check the documentation know it without needing to read it again.

In this PR I propose a standard DataFrame that:

• Is simple to understand
• Contains all the main dtypes
• Contains NaNs
• It can be groupped

Please feel free to propose a another one if you have a better idea, and reject this PR.

Let me know if the format of this docstring, as well as the DataFrame can be used for the rest of the method docstrings, and I'll work with them.

You can see how the html documentation looks like in the next screenshot:

[TomAugspurger]

Sorry for letting this sit unacknowledged for so long.

I think having a familiar dataframe would be nice, but I don't think other docstrings should feel forced to use it (not that you're proposing that).

As for this specific one, it seems good. The construction might be a bit long, but that's not really a problem for me.

[jorisvandenbossche]

In general, we don't include the standard imports (so those two) in the docstrings. Also in the tutorial docs we assume people have done these imports to not always have to repeat them

[TomAugspurger]

@datapythonista these imports can still be removed.

[jorisvandenbossche]

Can you capitalize the first word , so it reads like a full sentence? (although grammatically it isn't, but that is OK)

[jorisvandenbossche]

@datapythonista Thanks for working on this!

I agree it would be nice to use more similar dataframes throughout the examples. My main concern is that for many examples you don't need such a 'complex' dataframe (with all the different dtypes, also in this case it is eg not 'really' needed). And then it may also take attention away from the actual example / behaviour you want to show (IMO).

Anyhow we will probably want not only 1 default example, but a few with different characteristics to have a suitable one for different cases.
It would also be good to mention this in #15580 (a general issue about improving the docstrings)

[datapythonista]

Thanks a lot for the great feedback.

I updated the PR, so the example dataframe is more simple.

I think we can still have a familiar/consistent example dataframe, but show the minimum for the example to make sense. But this I mean that if it makes sense to have a boolean column, we can always use the same, but if it's not required, just keep a smaller dataframe with two or 3 columns.

There is just one thing I'd like to discuss, the imports. We said that we wanted the examples to be runnable, and I agree. And while obviously importing pandas each time is repetitive, I see a value of it:

• The code is 100% runnable
• The example can be executed as a doctest (even if we don't do it)
• For people who is just starting, these imports are not as obvious as for us. It happened to me before, in a project where they ommited the imports for being obvious (I guess), but they weren't to me.

I can imagine someone getting into pandas for the first time, trying to follow an example, and not knowing what's pd or np, or plt...

If that has been discussed, and you have a strong opinion about not having them, I'm happy to take them out. But my personal opinion is that they add more value, than the "noise" they add to the page.

Attached screenshot of the doc rendered as html:

[pep8speaks]

Hello @datapythonista! Thanks for updating the PR.

• In the file pandas/core/generic.py, following are the PEP8 issues :

Line 351:13: E722 do not use bare except'
Line 364:13: E722 do not use bare except'
Line 618:9: E722 do not use bare except'
Line 901:9: E722 do not use bare except'
Line 1795:17: E722 do not use bare except'
Line 1904:13: E722 do not use bare except'
Line 1912:13: E722 do not use bare except'
Line 2673:13: E722 do not use bare except'
Line 2882:13: E731 do not assign a lambda expression, use a def
Line 3321:13: E731 do not assign a lambda expression, use a def
Line 3336:9: E731 do not assign a lambda expression, use a def
Line 3341:9: E731 do not assign a lambda expression, use a def
Line 3346:9: E731 do not assign a lambda expression, use a def
Line 3359:17: E722 do not use bare except'
Line 5401:25: E722 do not use bare except'
Line 5441:29: E722 do not use bare except'
Line 6285:9: E731 do not assign a lambda expression, use a def

Comment last updated on July 15, 2017 at 15:34 Hours UTC

[jreback]

@datapythonista ignore the pep8 comments in the issue. once you rebase these will be gone.

[jreback]

thanks!