False positives for D410 in Numpy convention

[cdeil]

@farmersez - Thank you very much for adding the Numpy convention in #226!!!

Running it on some larger projects using the Numpy convention (Numpy, Scipy, Astropy), the most common message I see is

 D410: Missing blank line after section

Personally, I don't see how requiring an empty newline at the end of the docstring is useful.

But even if that is considered part of the convention, I think pydocstyle reports false positives.

For example for https://github.com/numpy/numpy/blob/master/doc/example.py I get

$ pydocstyle --convention=numpy example.py
example.py:1 at module level:
        D400: First line should end with a period (not 'd')
example.py:1 at module level:
        D205: 1 blank line required between summary line and description (found 0)
example.py:1 at module level:
        D404: First word of the docstring should not be `This`
example.py:38 in public function `foo`:
        D400: First line should end with a period (not 'e')
example.py:38 in public function `foo`:
        D205: 1 blank line required between summary line and description (found 0)
example.py:38 in public function `foo`:
        D202: No blank lines allowed after function docstring (found 1)
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Parameters')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Returns')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Other Parameters')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Raises')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('See Also')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Notes')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('References')
example.py:38 in public function `foo`:
        D410: Missing blank line after section ('Examples')

E.g. the last D410 is incorrect, I think: there is a blank line after the Examples section.

[shacharoo]

Glad you like it 😺
Apparently I misunderstood the convention as it's described in the HOWTO document. There's supposed to be a blank line after the whole section, not between the dashed line and the content itself. I'll upload a bugfix (hopefully) this weekend.

[cdeil]

There's supposed to be a blank line after the whole section, not between the dashed line and the content itself.

Yes.

In addition, I would suggest that at the very end of the docstring, the blank line is optional.
I could point out many docstrings in big projects using the Numpy docstring standard that have an empty line between sections (like Parameters and Returns or Examples, but not at the very end of the docstring. So requiring it there would again result in many warnings, and since it works just fine to have no blank line there, and looks a bit weird, I think pydocstyle should not warn about this.

Agreed? Or is this behaviour hard to implement or controversial?

I'll upload a bugfix (hopefully) this weekend.

Thank you very much!

[shacharoo]

I agree, even thought it's the way every numpy docstring I could find in their repo was formatted 😄
I could add a new "Missing blank line after last section" violation code and not include it in the numpy convention, allowing users to add it on their own if they wish to do so.

@Nurdok , do you think that's an overkill? Should we just ignore this case?

[shacharoo]

Fixed in #233 .

[cdeil]

@FarmerSez - Thank you very much.

I now get this, which are all valid suggestions to make in my opinion:

$ pydocstyle --convention=numpy example.py
example.py:1 at module level:
        D400: First line should end with a period (not 'd')
example.py:1 at module level:
        D404: First word of the docstring should not be `This`
example.py:1 at module level:
        D205: 1 blank line required between summary line and description (found 0)
example.py:38 in public function `foo`:
        D400: First line should end with a period (not 'e')
example.py:38 in public function `foo`:
        D202: No blank lines allowed after function docstring (found 1)
example.py:38 in public function `foo`:
        D401: First line should be in imperative mood; try rephrasing (found 'A')
example.py:38 in public function `foo`:
        D205: 1 blank line required between summary line and description (found 0)

🎉

[shacharoo]

😄