Wrap docstrings to 79 chars and check with flake8 #384
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Jupyter, IPython, and other IDEs don't usually render the rst in the docstrings and just show them literally. The problem is that many of these break lines at 79 characters. So docstrings with more characters look terrible in these settings and sometimes almost unreadable. Wrap all docstrings to 79 characters instead of Black's 88. Set `max-doc-length=79` to make flake8 check if any docstring exceeds it. The setting checks comments as well and we found no way of disabling that. So we'll format comments to 79 characters for consistency as well. Minor modifications to the first line of some docstrings was required to make them fit into a single line. Also made minor modifications on some doctests to wrap to 79 characters.
|
cc @GenericMappingTools/python-contributors please take note of this when writing your docstrings. flake8 will complain so you can't merge things in by mistake but it's good to know why flake8 is complaining :-) |
weiji14
approved these changes
Nov 27, 2019
CONTRIBUTING.md
Outdated
| #### Docstrings | ||
|
|
||
| **All docstrings** should follow the | ||
| [numpy style guide](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt). |
There was a problem hiding this comment.
The link has moved to https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
There was a problem hiding this comment.
👍 thanks for catching that!
|
Merged. Please note that this will impact all current PRs since they are likely to have conflicts with master now. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Jupyter, IPython, and other IDEs don't usually render the rst in the
docstrings and just show them literally. The problem is that many of
these break lines at 79 characters. So docstrings with more characters
look terrible in these settings and sometimes almost unreadable. Wrap
all docstrings to 79 characters instead of Black's 88. Set
max-doc-length=79to make flake8 check if any docstring exceeds it.The setting checks comments as well and we found no way of disabling
that. So we'll format comments to 79 characters for consistency as well.
Minor modifications to the first line of some docstrings was required to
make them fit into a single line. Also made minor modifications on some
doctests to wrap to 79 characters.
Reminders
make formatandmake checkto make sure the code follows the style guide.doc/api/index.rst.