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

Add Numpy docstring convention #129

Closed
cdeil opened this Issue Aug 12, 2015 · 14 comments

Comments

Projects
None yet
7 participants
@cdeil
Copy link

cdeil commented Aug 12, 2015

At https://github.com/GreenSteam/pep257#pep-257-docstring-style-checker you write "custom checks can be easily added, for example to cover NumPy docstring conventions.".

But it doesn't look like the numpy convention actually is available?
http://pep257.readthedocs.org/en/latest/search.html?q=numpy&check_keywords=yes&area=default
And it's also not clear to me (as a first-time user) how I would add it.

There's are many scientific Python packages using the Numpy docstring convention, so if you could add this (built-in to make it easy to use it), that would be wonderful!

@cdeil cdeil referenced this issue Aug 12, 2015

Open

Add pydocstyle docstring checker #325

0 of 3 tasks complete
@aldanor

This comment has been minimized.

Copy link

aldanor commented Sep 10, 2015

+1 to this, there's a ton of packages out there using numpy convention

@Korijn

This comment has been minimized.

Copy link

Korijn commented Apr 6, 2016

👍 it's completely unclear how this should be done, even though it's mentioned on the front page.

@Korijn

This comment has been minimized.

Copy link

Korijn commented Apr 7, 2016

I just went through the source and it looks like there really is no way to insert custom checks.

@sigmavirus24

This comment has been minimized.

Copy link
Member

sigmavirus24 commented Apr 7, 2016

All of you are correct. There's no way to provide pydocstyle a convention other than what's built-in to the tool (pep257).

If @Nurdok wants, I can add a way for pydocstyle to search entry-points for extra conventions. That said, I think pydocstyle may as well absorb the NumPy convention anyway. I don't think there will be too many other conventions to absorb and the two most popular will be covered.

@Korijn

This comment has been minimized.

Copy link

Korijn commented Apr 7, 2016

It would be great if it can be included, but to avoid giving more people false impressions, I think the README.md should be adjusted...

The framework for checking docstring style is flexible, and custom checks can be easily added, for example to cover NumPy docstring conventions.

This clearly isn't true, as it turns out.

@cdeil

This comment has been minimized.

Copy link

cdeil commented Apr 7, 2016

I think pydocstyle may as well absorb the NumPy convention anyway

For me, as a user, this would be the best solution (i.e. does what I need, simple install, simple documentation).

@Nurdok

This comment has been minimized.

Copy link
Member

Nurdok commented Apr 7, 2016

I fully intend for pydocstyle to come with numpy conventions out-of-the-box. It's true that the README is misleading on this topic. That sentence existed way before I became maintainer :) . I'll edit it before the next release.

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Apr 13, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Apr 13, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Apr 16, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Apr 18, 2016

@bilderbuchi

This comment has been minimized.

Copy link

bilderbuchi commented Jun 3, 2016

While implementing the numpy convention, it would probably be good to also add the Google convention (or at least accomodate a future addition), see here for a nice comparison. Afaik, both see major use, no?

@sigmavirus24

This comment has been minimized.

Copy link
Member

sigmavirus24 commented Jun 3, 2016

@bilderbuchi sure it would be good to add both, but not in the same pull request. The pull requests should be focused on one particular thing to reduce code that needs to be reviewed so @Nurdok has an easier time reviewing each one and merging each one. It will also maybe encourage other people here to review the numpy convention without getting confused about the Google convention being unhelpfully mixed in.

@bilderbuchi

This comment has been minimized.

Copy link

bilderbuchi commented Jun 5, 2016

alright, no problem. I just wanted to make sure that the system is going to be extensible to other conventions in the future.

@sigmavirus24

This comment has been minimized.

Copy link
Member

sigmavirus24 commented Jun 5, 2016

How does submitting them separately prevent that?

@bilderbuchi

This comment has been minimized.

Copy link

bilderbuchi commented Jun 7, 2016

By a PR submitter potentially coding this in a manner that does not allow easy extension to other conventions, but I assume that's a non-issue now.

@larsoner

This comment has been minimized.

Copy link
Contributor

larsoner commented Aug 30, 2016

If this is done, it ideally shouldn't duplicate effort with numpy/numpydoc#13. I suspect numpydoc might be a better place for it, actually, since all the machinery for sanity-checking NumPy-spec docstrings are already in that repo.

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 19, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 21, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 21, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 21, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 21, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 24, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 24, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 24, 2016

shacharoo added a commit to shacharoo/pydocstyle that referenced this issue Dec 24, 2016

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

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

@Nurdok

This comment has been minimized.

Copy link
Member

Nurdok commented Jan 20, 2017

Implemented in #226.

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