Add blackdoc and docformatter to wrap docstrings to 79 chars
See original GitHub issueDescription 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 https://github.com/pydata/xarray/pull/4177 as an example on how another library has implemented it.
Are you willing to help implement and maintain this feature? No
Issue Analytics
- State:
- Created 3 years ago
- Reactions:1
- Comments:5 (5 by maintainers)
Top Results From Across the Web
Python Black code formatter doesn't format docstring line ...
There's currently an open issue asking for this (although it also wants the line length limit for docstrings and strings to be 79)...
Read more >docformatter
Features. docformatter automatically formats docstrings to follow a subset of the PEP 257 conventions. Below are the relevant items quoted from PEP 257....
Read more >Contributors Guide
Write some documentation for your code (docstrings) and leave comments ... with Jupyter and IPython, keep docstrings limited to 79 characters per line....
Read more >[RFC-107] Wrap python docstring text after 79 characters - Jira
Users of open source Python expect <=79 character line lengths for docstrings when they ask for help in a Python terminal.
Read more >pygmt Changelog
Added two new PyGMT tutorials and EGU 2022 short course to external resources page ... Wrap docstrings to 79 chars and check with...
Read more >
Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free
Top Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
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
andpylint
. 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).Yes but our docstrings follow the NumPy style, not necessarily PEP257 😔 I haven’t seen those other tools, though. Might be worth investigating.