Skip to content

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

Closed
weiji14 opened this issue Jun 28, 2020 · 5 comments · Fixed by #642
Closed

Add blackdoc and docformatter to wrap docstrings to 79 chars #497

weiji14 opened this issue Jun 28, 2020 · 5 comments · Fixed by #642
Labels
good first issue Good for newcomers scipy-sprint Things to work on during the SciPy sprint!

Comments

@weiji14
Copy link
Member

weiji14 commented Jun 28, 2020

Description of the desired feature

blackdoc is like black, 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

@weiji14 weiji14 added good first issue Good for newcomers scipy-sprint Things to work on during the SciPy sprint! labels Jun 28, 2020
@seisman
Copy link
Member

seisman commented Jul 15, 2020

Just tried blackdoc. I think it can only format the codes in docstrings, but can't wrap other non-code docstrings.

@leouieda
Copy link
Member

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 👍

@weiji14
Copy link
Member Author

weiji14 commented Jul 15, 2020

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 .rst, .md files (instead of .py files). I found most of this quoted over at psf/black#144.

@leouieda
Copy link
Member

Yes but our docstrings follow the NumPy style, not necessarily PEP257 😔 I haven’t seen those other tools, though. Might be worth investigating.

@weiji14
Copy link
Member Author

weiji14 commented Jul 15, 2020

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 black and pylint. Adding one more into the mix might act as a barrier to new contributors (who often face dozens of lint errors on their first Pull Request).

@weiji14 weiji14 changed the title Add blackdoc to wrap docstrings to 79 chars Add blackdoc and docformatter to wrap docstrings to 79 chars Oct 27, 2020
@seisman seisman mentioned this issue Nov 6, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers scipy-sprint Things to work on during the SciPy sprint!
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants