Add Numpy docstring convention

[cdeil]

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!

[aldanor]

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

[Korijn]

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

[Korijn]

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

[sigmavirus24]

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]

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]

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]

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.

[bilderbuchi]

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]

@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]

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

[sigmavirus24]

How does submitting them separately prevent that?

[bilderbuchi]

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]

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.

[Nurdok]

Implemented in #226.