Description
Moving here conversation from #1693
Description:
Right now, docstring writing is left up completely to the contributors, who may not apply the correct style format.
In that issue, a tool can't be integrated correctly due to malformed parameter specification.
Current references to the format only include:
- This contributing section
- This checklist item in the PR Templates.
None of the above methods describe nor mention a user-agnostic way of checking compliance.
Proposed solution:
We could approach this issue by enforcing docstring validation tools, like numpydoc --validate, numpydoc.validate() or a module that wraps this function called numpydoc-validation.
However, mentioned linters in #1693 won't raise errors exactly for that. numpydoc raises errors that may hint the user.
Meanwhile, upgrading contributing.rst and/or the PR template to mention numpydoc --validate use case would be of help.
Alternatives:
- Module
pydocstyle
I haven't found a way of integrating it in sphinx builds, but there might be some way.
Additional context
This is a summary of one of my comments in #1693: when I first contributed to this repo, one of the things that I felt most discouraging was writing the docstring. If just expressing myself in a foreign language is not enough, trying to copy other's formats, then finding inconsistencies among them; and checking by building the docs, which takes time, are some of the bottlenecks that affect new contributions.