Result of a docstring formatter and some manual fixes on top of it by Pierre-Sassoulas · Pull Request #5624 · pylint-dev/pylint (original) (raw)
Conversation
This file contains hidden or 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
[ Show hidden characters]({{ revealButtonHref }})
Type of Changes
| Type | |
|---|---|
| ✓ | ✨ New feature |
| ✓ | 🔨 Refactoring |
Description
Add a pre-commit hook to format our docstring automatically for pep257 using https://github.com/myint/docformatter
Possible options:
usage: docformatter [-h] [-i | -c] [-r] [--wrap-summaries length]
[--wrap-descriptions length] [--blank]
[--pre-summary-newline] [--make-summary-multi-line]
[--force-wrap] [--range line line] [--version]
files [files ...]
Formats docstrings to follow PEP 257.
positional arguments:
files files to format or '-' for standard in
optional arguments:
-h, --help show this help message and exit
-i, --in-place make changes to files instead of printing diffs
-c, --check only check and report incorrectly formatted files
-r, --recursive drill down directories recursively
-e, --exclude exclude directories and files by names
--wrap-summaries length
wrap long summary lines at this length; set to 0 to
disable wrapping (default: 79)
--wrap-descriptions length
wrap descriptions at this length; set to 0 to disable
wrapping (default: 72)
--blank add blank line after description
--pre-summary-newline
add a newline before the summary of a multi-line
docstring
--make-summary-multi-line
add a newline before and after the summary of a one-
line docstring
--force-wrap force descriptions to be wrapped even if it may result
in a mess
--range line line apply docformatter to docstrings between these lines;
line numbers are indexed at 1
--version show program's version number and exit
Suggested by @DanielNoord #5620 (comment)
@Pierre-Sassoulas Not sure if this is the right tool for the job.
I took a quick look through the repository and some open issues can also be problematic for us.
For one there is:
PyCQA/docformatter#9 with associated PR PyCQA/docformatter#49.
It has been open since 2015 and I feel like it is one of the conventions we would like to enforce.
Another is:
PyCQA/docformatter#75
I'd like to find a good tool to do this, but this one might not be it sadly 😢
Pull Request Test Coverage Report for Build 1898844568
- 7 of 7 (100.0%) changed or added relevant lines in 7 files are covered.
- 1 unchanged line in 1 file lost coverage.
- Overall coverage remained the same at 93.994%
| Files with Coverage Reduction | New Missed Lines | % |
|---|---|---|
| pylint/lint/run.py | 1 | 72.79% |
| Totals | |
|---|---|
| Change from base Build 1882850152: | 0.0% |
| Covered Lines: | 14931 |
| Relevant Lines: | 15885 |
💛 - Coveralls
| """Script used to generate the features file before building the actual |
|---|
| documentation.""" |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please let's not do that. It's just not worth it. Not everything needs to be perfect.
@Pierre-Sassoulas I have started working on a little tool to do some of the things that docformatter does.
I think it should be ready for a 0.1.0 somewhere in the coming weeks. If we want to go ahead with a docstring auto formatter we could use it as we'll have more influence on what it changes.
Add docstring formatter in pre commit Result of a docstring formatter and some manual fixes on top of it
@Pierre-Sassoulas The latest fix also seems to have affected functional tests? Was this your intention? Are these 6k changes all manual?
Shall we convert this to draft while I work on pydocstringformatter a bit more? You're more than welcome to work on them as well! I'll make you contributor on the repository so you can assign yourself and we don't do double work!
We're getting close with pydocstringformatter.
Based on this I think we only need:
- Make splitting of summary and body more robust and then actually turn it on for
pylint - Do something with max line length (although this is very controversial and PEP 257 is very conservative with
max == 72) - Do something with "summaries" that span multiple lines. Should we add a period after them? Should we enforce single-line summaries?
I think all of these are already tracked or are on my to-do list so we don't need to open any new issues.
Let's keep this open as a reminder and progress tracker 😄
Closing in favor of #5910