black/docs
Richard Si c0a8e42243
Fix empty line handling when formatting typing stubs (#1646)
Black used to erroneously remove all empty lines between non-function
code and decorators when formatting typing stubs. Now a single empty
line is enforced.

I chose for putting empty lines around decorated classes that have empty
bodies since removing empty lines around such classes would cause a
formatting issue that seems to be impossible to fix.

For example:

```
class A: ...
@some_decorator
class B: ...
class C: ...
class D: ...

@some_other_decorator
def foo(): -> None: ...
```

It is easy to enforce no empty lines between class A, B, and C.
Just return 0, 0 for a line that is a decorator and precedes an stub
class. Fortunately before this commit, empty lines after that class
would be removed already.

Now let's look at the empty line between class D and function foo. In
this case, there should be an empty line there since it's class code next
to function code. The problem is that when deciding to add X empty lines
before a decorator, you can't tell whether it's before a class or a
function. If the decorator is before a function, then an empty line
is needed, while no empty lines are needed when the decorator is
before a class.

So even though I personally prefer no empty lines around decorated
classes, I had to go the other way surrounding decorated classes with
empty lines.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
2020-09-10 13:21:37 -07:00
..
_static Scrollable sidebar (#1457) 2020-05-23 11:56:50 -07:00
reference Use properly renamed function name in docs 2020-08-21 16:45:30 +02:00
authors.md Make doc generation a little smarter, update doc sections 2020-08-24 14:42:17 +02:00
black_primer.md Upgrade docs to Sphinx 3+ and add doc build test (#1613) 2020-08-21 00:06:41 +02:00
blackd.md Fix grammatical typos in black_primer and blackd (#1504) 2020-06-16 11:57:33 -07:00
change_log.md Fix empty line handling when formatting typing stubs (#1646) 2020-09-10 13:21:37 -07:00
compatible_configs.md Mention optional invalid W503 warning in pycodestyle 2020-09-01 13:18:46 +02:00
conf.py Make doc generation a little smarter, update doc sections 2020-08-24 14:42:17 +02:00
contributing_to_black.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
editor_integration.md Add links regarding Spotless integration for gradle/maven users (#1622) 2020-08-26 03:54:05 +02:00
github_actions.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
ignoring_unmodified_files.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
index.rst Upgrade docs to Sphinx 3+ and add doc build test (#1613) 2020-08-21 00:06:41 +02:00
installation_and_usage.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
make.bat add sphinx docs skeleton (#71) 2018-03-23 14:27:04 -07:00
Makefile add sphinx docs skeleton (#71) 2018-03-23 14:27:04 -07:00
pyproject_toml.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
requirements.txt Upgrade docs to Sphinx 3+ and add doc build test (#1613) 2020-08-21 00:06:41 +02:00
show_your_style.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00
the_black_code_style.md Clarify current trailing comma behavior in the docs 2020-09-01 13:24:31 +02:00
version_control_integration.md Fix dealing with generated files in docs 2020-08-21 16:45:30 +02:00