docs: Refactor pycodestyle/Flake8 compatibility docs

.flake8

@@ -1,8 +1,8 @@
 [flake8]
 # B905 should be enabled when we drop support for 3.9
-ignore = E203, E266, E501, E704, W503, B905, B907
+ignore = E203, E266, E501, E701, E704, W503, B905, B907
 # line length is intentionally set to 80 here because black uses Bugbear
-# See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
+# See https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#bugbear for more details
 max-line-length = 80
 max-complexity = 18
 select = B,C,E,F,W,T4,B9

docs/compatible_configs/flake8/.flake8

@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701

docs/compatible_configs/flake8/setup.cfg

@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701

docs/compatible_configs/flake8/tox.ini

@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701

docs/compatible_configs/pycodestyle/.flake8

@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701

docs/compatible_configs/pycodestyle/setup.cfg

@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701

docs/compatible_configs/pycodestyle/tox.ini

@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701

docs/faq.md

@@ -77,13 +77,10 @@ following will not be formatted:
 - invalid syntax, as it can't be safely distinguished from automagics in the absence of
   a running `IPython` kernel.
 
-## Why are Flake8's E203 and W503 violated?
+## Why does Flake8 report warnings?
 
-Because they go against PEP 8. E203 falsely triggers on list
-[slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
-readability because operators are misaligned. Disable W503 and enable the
-disabled-by-default counterpart W504. E203 should be disabled while changes are still
-[discussed](https://github.com/PyCQA/pycodestyle/issues/373).
+See
+[Using _Black_ with other tools](guides/using_black_with_other_tools.md#why-pycodestyle-warnings).
 
 ## Which Python versions does Black support?
 

docs/guides/using_black_with_other_tools.md

@@ -134,78 +134,124 @@ profile = black
 
 </details>
 
-### Flake8
+### pycodestyle
 
-[Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
-possible bugs, stylistic errors, etc. For the most part, Flake8 follows
+[pycodestyle](https://pycodestyle.pycqa.org/) is a code linter. It warns you of syntax
+errors, possible bugs, stylistic errors, etc. For the most part, pycodestyle follows
 [PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors.
 There are a few deviations that cause incompatibilities with _Black_.
 
 #### Configuration
 
 ```
 max-line-length = 88
-extend-ignore = E203, E704
+ignore = E203,E701
 ```
 
+(labels/why-pycodestyle-warnings)=
+
 #### Why those options above?
 
+##### `max-line-length`
+
+As with isort, pycodestyle should be configured to allow lines up to the length limit of
+`88`, _Black_'s default.
+
+##### `E203`
+
 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
-whitespace around slice operators. Due to this, Flake8 will raise
-`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
-should be configured to ignore it via `extend-ignore = E203`.
+whitespace around slice operators. Due to this, pycodestyle will raise
+`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, it
+should be disabled.
+
+##### `E701` / `E704`
+
+PEP 8 states (and has always stated), "Blank lines may be omitted between a bunch of
+related one-liners." _Black_ takes advantage of this by putting the pass statement of
+dummy implementations on the same line as the colon, reducing the number of lines while
+improving readability. This does go against pycodestyle's
+`E701 multiple statements on one line (colon)`. Its disabled-by-default
+`E704 multiple statements on one line (def)` rule may also raise warnings in this
+situation and should not be enabled.
+
+##### `W503`
 
 When breaking a line, _Black_ will break it before a binary operator. This is compliant
 with PEP 8 as of
 [April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599).
 There's a disabled-by-default warning in Flake8 which goes against this PEP 8
 recommendation called `W503 line break before binary operator`. It should not be enabled
-in your configuration.
-
-Also, as like with isort, flake8 should be configured to allow lines up to the length
-limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
+in your configuration. You should use its counterpart
+`W504 line break after binary operator` instead.
 
 #### Formats
 
 <details>
-<summary>.flake8</summary>
+<summary>setup.cfg, .pycodestyle, tox.ini</summary>
 
 ```ini
-[flake8]
+[pycodestyle]
 max-line-length = 88
-extend-ignore = E203, E704
+ignore = E203,E701
 ```
 
 </details>
 
-<details>
-<summary>setup.cfg</summary>
+### Flake8
 
-```ini
+[Flake8](https://pypi.org/p/flake8/) is a wrapper around multiple linters, including
+pycodestyle. As such, it has many of the same issues
+
+#### Bugbear
+
+It's recommended to use [the Bugbear plugin](https://github.com/PyCQA/flake8-bugbear)
+and enabling
+[its B950 check](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings#:~:text=you%20expect%20it.-,B950,-%3A%20Line%20too%20long)
+instead of using Flake8's E501, because it aligns with
+[Black's 10% rule](the_black_code_style/current_style.md#line-length).
+
+Install Bugbear and use the following config:
+
+```
+[flake8]
+max-line-length = 80
+extend-select = B950
+extend-ignore = E203,E501,E701
+```
+
+#### Minimal Configuration
+
+In cases where you can't or don't want to install Bugbear, you can use this minimally
+compatible config:
+
+```
 [flake8]
 max-line-length = 88
-extend-ignore = E203, E704
+extend-ignore = E203,E701
 ```
 
-</details>
+#### Why those options above?
+
+See [the pycodestyle section](#why-pycodestyle-warnings) above.
+
+#### Formats
 
 <details>
-<summary>tox.ini</summary>
+<summary>.flake8, setup.cfg, tox.ini</summary>
 
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203, E704
+extend-ignore = E203,E701
 ```
 
 </details>
 
 ### Pylint
 
-[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same
-checks as flake8 and more. In particular, it has more formatting checks regarding style
-conventions like variable naming. With so many checks, Pylint is bound to have some
-mixed feelings about _Black_'s formatting style.
+[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has many of
+the same checks as Flake8 and more. It particularly has more formatting checks regarding
+style conventions like variable naming.
 
 #### Configuration
 
@@ -252,35 +298,3 @@ max-line-length = "88"
 ```
 
 </details>
-
-### pycodestyle
-
-[pycodestyle](https://pycodestyle.pycqa.org/) is also a code linter like Flake8.
-
-#### Configuration
-
-```
-max-line-length = 88
-ignore = E203
-```
-
-#### Why those options above?
-
-pycodestyle should be configured to only complain about lines that surpass `88`
-characters via `max_line_length = 88`.
-
-See
-[Why are Flake8’s E203 and W503 violated?](https://black.readthedocs.io/en/stable/faq.html#why-are-flake8-s-e203-and-w503-violated)
-
-#### Formats
-
-<details>
-<summary>setup.cfg</summary>
-
-```cfg
-[pycodestyle]
-ignore = E203
-max_line_length = 88
-```
-
-</details>

docs/the_black_code_style/current_style.md

@@ -143,45 +143,20 @@ significantly shorter files than sticking with 80 (the most popular), or even 79
 by the standard library). In general,
 [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
 
-If you're paid by the line of code you write, you can pass `--line-length` with a lower
-number. _Black_ will try to respect that. However, sometimes it won't be able to without
-breaking other rules. In those rare cases, auto-formatted code will exceed your allotted
-limit.
+If you're paid by the number of lines of code you write, you can pass `--line-length`
+with a lower number. _Black_ will try to respect that. However, sometimes it won't be
+able to without breaking other rules. In those rare cases, auto-formatted code will
+exceed your allotted limit.
 
 You can also increase it, but remember that people with sight disabilities find it
 harder to work with line lengths exceeding 100 characters. It also adversely affects
 side-by-side diff review on typical screen resolutions. Long lines also make it harder
 to present code neatly in documentation or talk slides.
 
-#### Flake8
+#### Flake8 / pycodestyle
 
-If you use Flake8, you have a few options:
-
-1. Recommended is using [Bugbear](https://github.com/PyCQA/flake8-bugbear) and enabling
-   its B950 check instead of using Flake8's E501, because it aligns with Black's 10%
-   rule. Install Bugbear and use the following config:
-
-   ```ini
-   [flake8]
-   max-line-length = 80
-   ...
-   select = C,E,F,W,B,B950
-   extend-ignore = E203, E501, E704
-   ```
-
-   The rationale for B950 is explained in
-   [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings).
-
-2. For a minimally compatible config:
-
-   ```ini
-   [flake8]
-   max-line-length = 88
-   extend-ignore = E203, E704
-   ```
-
-An explanation of why E203 is disabled can be found in the [Slices section](#slices) of
-this page.
+See [Using _Black_ with other tools](guides/using_black_with_other_tools.md) about
+linter compatibility.
 
 ### Empty lines