Allow blank lines after multi-line function docstrings

[anntzer]

Currently, pydocstyle warns by default when a function docstring is followed by a blank line (D202). However, a careful reading of PEP257 indicates that this rule should only apply to one-line docstrings, not to multiline docstrings: the sole sentence regarding this, "There's no blank line either before or after the docstring.", occurs in the "One-line docstrings" section, immediately after the "The closing quotes are on the same line as the opening quotes. This looks better for one-liners." sentence which clearly only applies to one-line docstrings. Allowing an empty line after the function docstring also makes sense if e.g. the function body contains empty lines: in something like

def func():
    """
    Some docstring.

    Some more stuff.
    """
    do_this()
    do_that()

    do_this_again()
    do_that_again()

if there's no empty line after the docstring, I personally feel the docstring "binds" too closely to the first part of the body at the expense of the second part.

[cdeil]

In our project we are using black and pydocstyle.

There is the case of inner functions following docstrings where black and pydocstyle` disagree, one of the few problems that come up when using both tools.

Example: https://github.com/gammapy/gammapy/blob/a9ca5c02b191a0f03212163c106e35f45f05850c/gammapy/stats/significance.py#L111-L125

pydocstyle tells me to remove the empty line after the docstring:

gammapy/stats/significance.py:112 in public function `significance_to_probability_normal_limit`:
        D202: No blank lines allowed after function docstring (found 1)

And then I run black, it will add the empty line back, because it puts empty lines around inner functions:
https://github.com/python/black#empty-lines

To me, the black style seems reasonable, so I'm bringing this up here instead of with black.

Would you be willing to change D202 and make it so that this formatting is allowed and will not raise a D202?

def spam():
    """Spam."""

    def ham():
        return "ham"

    return "spam"

[ala-ableton]

AFAICS, this issue is fixed by #426 and could be closed.

[anntzer]

Actually I think this is not fully resolved: as noted in the original message, I think that a careful reading of PEP257 indicates that the prohibition for a blank link after the docstring only applies to single-line docstrings (the point literally appears in the "one-line docstrings" section).

[divypandya]

In our project we are using black and pydocstyle.

There is the case of inner functions following docstrings where black and pydocstyle` disagree, one of the few problems that come up when using both tools.

Example: https://github.com/gammapy/gammapy/blob/a9ca5c02b191a0f03212163c106e35f45f05850c/gammapy/stats/significance.py#L111-L125

pydocstyle tells me to remove the empty line after the docstring:

gammapy/stats/significance.py:112 in public function `significance_to_probability_normal_limit`:
        D202: No blank lines allowed after function docstring (found 1)

And then I run black, it will add the empty line back, because it puts empty lines around inner functions:
https://github.com/python/black#empty-lines

To me, the black style seems reasonable, so I'm bringing this up here instead of with black.

Would you be willing to change D202 and make it so that this formatting is allowed and will not raise a D202?

def spam():
    """Spam."""

    def ham():
        return "ham"

    return "spam"

Faced the same problem with inner functions. I added a comment just after the docstring of outer functions and left a new line before the inner function, worked for me.