DOC: Misc numpydoc syntax fixing.

[Carreau]

This uses https://github.com/Carreau/velin to try to automatically fix a
couple of issues in docstrings to match the numpydoc syntax.

• Space before colon in Parameter sections is necessary for numpydoc to
  properly recognize parameter name and type.
• Naming of sections in numpydoc is plural usually

This also remove a couple of documented parameters that don't exists
(either removed, or copy-past is my guess).

[welcome]

Hi! Welcome, and thanks for opening this pull request. We have some guidelines for new pull requests, and soon you'll hear back about the results of our tests and continuous integration checks. Thank you for your contribution!

[neutrinoceros]

Very cool, thanks Matthias !
I see that Velin exposes a pre-commit hook as well, which is awesome. Would you mind adding it to our .pre-commit-config.yaml ?

[munkm]

This is great! Thanks Matthias!!!!

[munkm]

Maybe we can open a "good first contribution" issue to add the pre-commit hook! That would be a nice fix for a new contributor. What do you think @neutrinoceros ?

[neutrinoceros]

I think it'd take much less time to do it myself TBF. I'm giving priority to Matthias here as courtesy to the author :)

[munkm]

I think it'd take much less time to do it myself TBF.

That's the nature of all "good first contribution" issues 🙂

[neutrinoceros]

True. I also don't think we should advertise "solve our infrastructure" as good first issues. Most potential contributors wouldn't know what to do, and the others could question our ability to do the job.

[munkm]

If somebody questions our ability to do our job because we're trying to build community with good, technical, not demeaning "good first contribution" labels on issues that's their problem, not ours.

[Carreau]

I see that Velin exposes a pre-commit hook as well, which is awesome. Would you mind adding it to our .pre-commit-config.yaml ?

I think it is not yet stable enough to be added as a an alway on pre-commit; there are still bugs, like for example if you forget the blank line before the Return section, because of how numpydoc works it will just nuke the section.

There are also case where it get things wrong like:

Yields
------

A tuple of :class:`FooBar`

It will replace to : class:`FooBar` which is invalid RST syntax.

So maybe a bit later, when I'm more confident that it won't just throw away a paragraph you took 10 minutes to write :-)

[neutrinoceros]

Totally fine by me. In that case we can merge this as in AFAIC. Thanks again !

[welcome]

Hooray! Congratulations on your first merged pull request! We hope we keep seeing you around! 🎆