-
Notifications
You must be signed in to change notification settings - Fork 963
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
CD/CI tools for docstring format validation #1698
Comments
For future reference: https://github.com/numpy/numpydoc/pull/312/files |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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:
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 callednumpydoc-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 mentionnumpydoc --validate
use case would be of help.Alternatives:
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.
The text was updated successfully, but these errors were encountered: