-
Notifications
You must be signed in to change notification settings - Fork 229
Add blackdoc and docformatter to wrap docstrings to 79 chars #497
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
Comments
Just tried blackdoc. I think it can only format the codes in docstrings, but can't wrap other non-code docstrings. |
The problem with formatting the dosctring text is that it’s restructuredtext, not Python. So the rules are different. But even if blackdoc does only the doctests, it would be nice to have automated 👍 |
A quick search turns up docformatter that follows PEP 257 (didn't realize there's a docstring convention)! We might be able to mix both, but not sure how well they play nicely with one another. There's also PEP 287 which is specifically for RestructuredText, and blacken-docs that looks similar to blackdoc but only for |
Yes but our docstrings follow the NumPy style, not necessarily PEP257 😔 I haven’t seen those other tools, though. Might be worth investigating. |
There's some similarities between the standards (see this stackoverflow answer for an overview), but yes, let's stick to numpydoc. Actually after some thought, it might be better to make this an optional tool, since we already have |
Description of the desired feature
blackdoc
is likeblack
, but for docstrings! This will help with applying #384, and make our docstrings consistent with our code.Would prefer for someone new-ish to take this on. Some knowledge of git commit-hooks would be useful, but you can see pydata/xarray#4177 as an example on how another library has implemented it.
Are you willing to help implement and maintain this feature? No
The text was updated successfully, but these errors were encountered: