Result of a docstring formatter and some manual fixes on top of it

[Pierre-Sassoulas]

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)

[DanielNoord]

@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 😢

[coveralls]

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

[cdce8p]

Please let's not do that. It's just not worth it. Not everything needs to be perfect.

[DanielNoord]

@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.

[DanielNoord]

@Pierre-Sassoulas The latest fix also seems to have affected functional tests? Was this your intention? Are these 6k changes all manual?

[Pierre-Sassoulas]

Are these 6k changes all manual?

It's docformatter + manual and semi manual (sed) after that. I should not have touched the functional tests. I'm going to fix that, but I think doing DanielNoord/pydocstringformatter#3 and DanielNoord/pydocstringformatter#5 before would be cleaner. Are you already working on it or can I work on them ?

[DanielNoord]

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!

[DanielNoord]

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 😄

[Pierre-Sassoulas]

Closing in favor of #5910