Skip to content
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

Open
echedey-ls opened this issue Mar 15, 2023 · 1 comment
Open

CD/CI tools for docstring format validation #1698

echedey-ls opened this issue Mar 15, 2023 · 1 comment

Comments

@echedey-ls
Copy link
Contributor

echedey-ls commented Mar 15, 2023

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 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:

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.

@echedey-ls echedey-ls changed the title CD/CI tools of docstring format validation CD/CI tools for docstring format validation Mar 16, 2023
@echedey-ls
Copy link
Contributor Author

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
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant