Standardise newlines after module-level docstrings

[jpy-git]

Description

Closes #1872.

Does 2 things:
a) Refactor EmptyLineTracker for more consistent look-back logic. Simplifies logic by removing complex interactions between before and after for various rules.

b) Standardise newlines after module-level docstrings. We now enforce 1 newline after both single and multi line docstrings.
e.g.

"""docstring"""

import foo

"""docstring

blah blah blah
"""

import foo

Checklist - did you ...

• Add a CHANGELOG entry if necessary?
• Add / update tests if necessary?
• Add new / update outdated documentation?

[github-actions]

diff-shades results comparing this PR (c8275d0) to main (c940f75). The full diff is available in the logs under the "Generate HTML diff report" step.

╭──────────────────────── Summary ─────────────────────────╮
│ 14 projects & 572 files changed / 571 changes [+554/-17] │
│                                                          │
│ ... out of 2 206 193 lines, 10 579 files & 23 projects   │
╰──────────────────────────────────────────────────────────╯

Differences found.

What is this? | Workflow run | diff-shades documentation

[JelleZijlstra]

The number of changes seem surprisingly small. Only a few hundred out of 10k files have a multi-line docstring?

[jpy-git]

No, it makes sense based on the module docstrings that diff-shades checks:

Total counts:
no_docstring:  10151
single_line_docstring:  183
multi_line_docstring:  721

[felix-hilden]

Man, huge thanks for taking on all these issues!

I think I'd prefer the newlines to be added to multiline docstrings as well, just for consistency. Not strongly though, and against my own habits and what I said in the original issue I know, but still.

About the preview handling: certainly this is a feature we'd carry over without question, so no biggie, but having the clarity of being able to search for usages of a potential Preview.docstring_newlines (or similar) was intended to help in picking individual changes for stable. Not that it's likely that we have other changes in EmptyLineTracker so it would be fairly easy to find this one thing, but anyways. Example PR: #2916

I'm trying to slowly get into the processing code. Your modifications seem sensible, but I'm not the authority on that I'm afraid 😄 I do trust the tests though, nice work!

[jpy-git]

About the preview handling: certainly this is a feature we'd carry over without question, so no biggie, but having the clarity of being able to search for usages of a potential Preview.docstring_newlines (or similar) was intended to help in picking individual changes for stable.

Good point, will update to reference the specific preview mode 😄

I think I'd prefer the newlines to be added to multiline docstrings as well, just for consistency.

Sounds good 👍

[felix-hilden]

Much better, and a nice simplification! Again, provided that other maintainers also agree with the style, and that the implementation itself is sound.

[ichard26]

Implementation-wise this is good to go¹ (minus all 'em merge conflicts >.<), but I need to catch up all of the discussion around docstrings and newlines (and probably quote placement too) before approving the PR as a whole.

Also, once we settle on a style, could we put it in the future code style documentation? I know this is minor, but as we're trying to keep Black relatively stable, we should be explicit when we do change the style.

Footnotes

1. I love the refactor, it makes EmptyLineTracker so much nicer to follow :) ↩

[JelleZijlstra]

Unfortunately this has a lot of merge conflicts, sorry for dropping the ball here.

[aqeelat]

@JelleZijlstra does it mean that you need help rebasing it?

[JelleZijlstra]

Yes, somebody will have to rebase this.

[DanielNoord]

@JelleZijlstra I can't rebase on this PR but I'd be happy to invest the time to get this finished. Are you okay with me rebasing this and opening a new PR? (Or somebody else for that matter)

[DanielNoord]

Went ahead and created #3932, please consider reviewing it. Very much open to feedback on how to change the code to make the PR mergeable!

[JelleZijlstra]

Merged #3932, thanks!