DOC: Improving docstring of pop method (#16416)
State: closed

 - [ ] closes #xxxx
 - [ ] tests added / passed
 - [X] 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:

![pandas_pop_doc](https://cloud.githubusercontent.com/assets/10058240/26524333/883d96e6-4327-11e7-856c-31cc3446b268.png)


Labels:
name: Docs

Comments:
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.
@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 https://github.com/pandas-dev/pandas/issues/15580 (a general issue about improving the docstrings)
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:

![pandas_doc_v2](https://cloud.githubusercontent.com/assets/10058240/26757536/c390d02a-48b6-11e7-9aea-9523abf3ebd0.png)

Hello @datapythonista! Thanks for updating the PR.

 - In the file [`pandas/core/generic.py`](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py), following are the PEP8 issues :

> [Line 351:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L351): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 364:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L364): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 618:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L618): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 901:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L901): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 1795:17](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L1795): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 1904:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L1904): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 1912:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L1912): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 2673:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L2673): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 2882:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L2882): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def
> [Line 3321:13](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L3321): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def
> [Line 3336:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L3336): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def
> [Line 3341:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L3341): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def
> [Line 3346:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L3346): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def
> [Line 3359:17](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L3359): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 5401:25](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L5401): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 5441:29](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L5441): [E722](https://duckduckgo.com/?q=pep8%20E722) do not use bare except'
> [Line 6285:9](https://github.com/pandas-dev/pandas/blob/0343b90d5c6aea35826125021f516284b655bcb3/pandas/core/generic.py#L6285): [E731](https://duckduckgo.com/?q=pep8%20E731) do not assign a lambda expression, use a def



##### Comment last updated on July 15, 2017 at 15:34 Hours UTC
@datapythonista ignore the pep8 comments in the issue. once you rebase these will be gone.
thanks!