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

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

[github-actions[bot]]

diff-shades results comparing this PR (c8275d057814a360e463346e9ecf00388a3557b2) to main (c940f75d5b646777427aef1beb18a0d2c391f5e2). 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

[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 👍

[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 https://github.com/psf/black/pull/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!