DOC: Clarify output of diff (returned type and possible overflow)

[mproszewska]

• closes DOC: diff() when using unsigned ints #28909
• tests passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• note about dtype in diff in Dataframa and Series

[WillAyd]

Thanks for the PR. I don't understand the comments though - can you maybe provide code for what you are trying to express?

[datapythonista]

Thanks for working on this @mproszewska. Agree with @WillAyd, I don't understand what's the comment trying to explain. I can read what's the problem in the issue, but I don't think the added comment is helping users understand. Can you give it another try?

[pep8speaks]

Hello @mproszewska! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2020-05-31 13:11:56 UTC

[datapythonista]

Thanks for working on this @mproszewska. Looking better, but just one idea about how to approach the problem.

And also, I think this PR is a good opportunity to unify the two docstrings that you're updating, so there is just one, and the other method reuses it. We have a @doc decorator for it. The general idea would be something like:

class Series:
    @doc(klass='Series', extra_params='', ...)
    def diff(...):
    """
    First discrete difference of element.

    Calculates the difference of a {klass} element compared with another
    ...
    """
    ...

class DataFrame:
    @doc(Series.diff, klass='DataFrame', extra_param="axis : {0 or 'index', 1 or 'columns'}, default 0...", ...)
    def diff(...):
    ...  # no docstring here, since it's reused the one from `Series.diff`

You have an example of using @doc in #32787

Thanks for helping with this, let me know if you have any question.

[datapythonista]

Thanks @mproszewska. Can you use another variable {examples} for the examples, instead of using Appender (we want to deprecate Appender and use doc instead).

Also, you've got conflicts. And if you can run scripts/validate_docstrings.py pandas.Series.diff and same for the other docstring, to make sure that they render as you expect, and that no error is reported, that would be great.

Thanks!

[mproszewska]

Also, you've got conflicts. And if you can run scripts/validate_docstrings.py pandas.Series.diff and same for the other docstring, to make sure that they render as you expect, and that no error is reported, that would be great.

I can't run this script. I have numpydoc installed but I keep getting

Traceback (most recent call last):
  File "scripts/validate_docstrings.py", line 50, in <module>
    from numpydoc.validate import validate, Docstring  # noqa: E402 isort:skip
ModuleNotFoundError: No module named 'numpydoc.validate'

I checked changed docs with help(pd.Series.diff) and they seemed fine.

[datapythonista]

You need to install the development version of numpydoc. It's in environment.yml. If you're using conda and installing things in the recommended way, a simple conda env update in the root directory of pandas should get you the right version.

[datapythonista]

Looks good, thanks for working on this @mproszewska

Only thing is that in the examples parameter I think we usually use textwrap.dedent, to have the text indented, and make clear what it's the parameter, and where the function is defined. Can you have a look at other cases, and see if this is correct, please? Thanks!

[datapythonista]

Thanks @mproszewska

Can you run ./scripts/validate_docstrings.py pandas.DataFrame.diff and make sure it doesn't report any error please?

And you'll have to run black to fix the CI. Thanks!

[datapythonista]

Thanks @mproszewska, very nice PR, lgtm

[jbrockmendel]

@mproszewska can you see if you can get the CI passing

[mproszewska]

test_diff was checking stacklevel of warning produced by diff. After my changes in documentation warning was raised in _decorators.py file instead of test_algos.py. I changed test so that stacklevel is not checked. I'm not sure if that's the best idea, but I couldn't find any other way.

[datapythonista]

We need to wait for #33160 before we can merge this. But you can find where the FutureWarning and change the stack level for now, and may be after that PR is merged we'll need to change that number again, but that should be easy once you found where it's being defined.

[mproszewska]

I changed stacklevel. Everything should be fine now.

[jreback]

@mproszewska can you merge master and ping on green.

@datapythonista over to you.

[datapythonista]

Thanks @mproszewska, great PR.

Can you have a look at https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.diff.html when it's updated, and see that everything looks as expected please?