New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

False positives for D410 in Numpy convention #230

Closed
cdeil opened this Issue Jan 22, 2017 · 6 comments

Comments

Projects
None yet
2 participants
@cdeil
Copy link

cdeil commented Jan 22, 2017

@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

This comment has been minimized.

Copy link
Member

shacharoo commented Jan 26, 2017

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.

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Jan 27, 2017

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Jan 27, 2017

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Jan 27, 2017

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Jan 27, 2017

@cdeil

This comment has been minimized.

Copy link

cdeil commented Jan 27, 2017

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!

@Nurdok Nurdok referenced this issue Jan 28, 2017

Merged

Fix numpy d410 #233

@shacharoo

This comment has been minimized.

Copy link
Member

shacharoo commented Jan 28, 2017

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 added a commit to shacharoo/pydocstyle that referenced this issue Jan 28, 2017

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Jan 28, 2017

@shacharoo shacharoo closed this Apr 19, 2017

@shacharoo

This comment has been minimized.

Copy link
Member

shacharoo commented Apr 19, 2017

Fixed in #233 .

@cdeil

This comment has been minimized.

Copy link

cdeil commented Apr 19, 2017

@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

This comment has been minimized.

Copy link
Member

shacharoo commented Apr 19, 2017

😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment