Add line wrapping to summaries of docstrings

[Pierre-Sassoulas]

Partially handles #7, it's not even close right now 😄 The line wrapping fail because there are space before and after the leading string.

• Line wrapping after certain line length
• make line length configurable, search for settings of other tools (black, pylint)
• Break up multiple sentences on first line into summary and main block (see PEP 256)
• Handle numpy/google style docstrings gracefully with line wrapping

[DanielNoord]

I like how it auto-formatted our own test examples 😄

[coveralls]

Pull Request Test Coverage Report for Build 2190458152

• 18 of 18 (100.0%) changed or added relevant lines in 2 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 2190234489:	0.0%
Covered Lines:	444
Relevant Lines:	444

---

💛 - Coveralls

[DanielNoord]

@Pierre-Sassoulas I have started working some more on this as it is a nice little job I can do in between other (personal) stuff.

This is still WIP, but in order for this to remain manageable I'd like to focus on wrapping summaries for now. In this PR we should add that basic functionality with the line length as ordered by PEP 8 (which is 72 😮).
Before releasing this we should probably also allow setting the max line length in some way.

One thing I haven't yet fixed is how to handle docstrings that haven't been split. For example:

"""My beautiful docstring
This function will do a number of things:
bla di bla
"""

Should be

"""My beautiful docstring

This function will do a number of things:
bla di bla
"""

That makes it much easier for this to line wrap. However since the \n\n is missing, this current iteration will now wrap this to:

"""My beautiful docstring This function will do a number of things: bla di bla."""

[Pierre-Sassoulas]

in order for this to remain manageable I'd like to focus on wrapping summaries for now

Yes, let's not do too much at once.

add that basic functionality with the line length as ordered by PEP 8 (which is 72 😮).

I think this is unreasonable and we should use 88 by default (black's default).

this current iteration will now wrap this to: """My beautiful docstring This function will do a number of things: bla di bla."""

Is it really problematic ? I mean if we encounter an end of sentence punctuation we could cut easily after it then line wrap. Maybe we should first add end of sentence punctuation if there's a \n then line wrap ? If there's no \n at all in the docstring we do not add a ., and we line wrap ?

[DanielNoord]

add that basic functionality with the line length as ordered by PEP 8 (which is 72 😮).

I think this is unreasonable and we should use 88 by default (black's default).

Personally I'd like to strictly adhere to the PEP's and make it very clear how to avoid this (awful) default. Something like "we recommend running with pydocstringformatter --line-length=88" in the first sections of the README.
Adhering strictly to the PEP's avoids any future discussion about defaults etc, which is something that's likely going to come up with a strict tool like this.

this current iteration will now wrap this to: """My beautiful docstring This function will do a number of things: bla di bla."""

Is it really problematic ? I mean if we encounter an end of sentence punctuation we could cut easily after it then line wrap. Maybe we should first add end of sentence punctuation if there's a \n then line wrap ? If there's no \n at all in the docstring we do not add a ., and we line wrap ?

We do cut in SplitSummaryAndDocstringFormatter. So pydocstringformatter --linewrap-full-docstring --split-summary-body . works best. However, that formatter is still optional as I'm not fully satisfied with how we determine what is a summary and what is a description. Furthermore, I think it's a good design philosophy not to depend too much on other checkers being activated. That's also why I use quotes here instead of """. If people really want to use ''' or " then this formatter won't break that.

We could also think: let's wrap everything and if the user doesn't want us to they should clearly indicate what is a summary and what isn't. However, I think that's not the most user-friendly approach.

I'll think about this some more and hopefully come up with something elegant.

[Pierre-Sassoulas]

make it very clear how to avoid this (awful) default

Hmm, why put the bad default value in the first place if we think everyone need to change it ? black is pretty successful with a "sane default" and the possibility to change it to the value from pep8 if you're a purist (and 79 is more reasonable than 72 too). Having good default values is pretty important imo.

avoids any future discussion

If the default is sane it's going make the discussion less likely. I think that if black default was 79, the first thing to do when adopting black would be to discuss between 79, 80, 90, 100, 110, 120 for line length. As it's reasonable, I think discussions happen less often.

Also it would not be a problem if we go check the line length for black/pylint/flake8 ourselves in the configuration files later on.

We could also think: let's wrap everything and if the user doesn't want us to they should clearly indicate what is a summary and what isn't

Pretty much agree with that, if the docstring is bad we cannot make it good magically. crap in, crap out !

[DanielNoord]

@Pierre-Sassoulas Could you review this 😄

[github-actions]

According to the primer, this change has no effect on the checked open source code. 🤖🎉