Add Black compatible configurations in documentation (#1366 & #1205) (#1371)

* Add Black compatible configs in docs ( #1366 & #1205)

When users of Black are starting a new project or are adding Black to their
existing projects, they will usually have to config their existing tools like
flake8 to be compatible with Black. Usually, these configs are the same across
different projects. Yet, there isn't any consolidated infomation on what configs
are compatible. Leaving users of Black to dig out any infomation they can find
in README.md.

* Fix a bad max-line-length value

* Clean up pylint's configs

* Add explanations for each configurations

Copying and pasting code without understanding it is a bad idea. This goes the same
for users copying and pasting configurations.

* Capitalize Pylint

* Link from the README

* Fix the isort configuration

I referenced the wrong source. I used a pesonal configuration, not a pure Black-
compatible configuration.

* Improve the config explanations

The explanation for the isort configuration was pretty bad. After having fixed the
configuration (see commit 01c55d1), improving the its explanation was necessary to
make it more user-friendly and understandable. Also added fenced code blocks of the
raw configuration options so the explanations make sense.

* Improve README wording slightly

* Add @hugovk, @JelleZijlstra + my suggestions

Co-authored-by: Cooper Lees <cooper@fb.com>

diff --git a/README.md b/README.md
index 5a9d6ea686e3fd293740924a7a02ce703ef2a1a9..43d47fc6dfabbaa10170ecaaf84f524d6031eb5a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -127,6 +127,16 @@ _Black_ is a well-behaved Unix-style command-line tool:
 - it only outputs messages to users on standard error;
 - exits with code 0 unless an internal error occurred (or `--check` was used).
 
+### Using _Black_ with other tools
+
+While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
+about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
+[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
+should be configured to neither warn about nor overwrite _Black_'s changes.
+
+Actual details on _Black_ compatible configurations for various tools can be found in
+[compatible_configs](./docs/compatible_configs.md).
+
 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](#used-by) by many projects, small and big. It

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
new file mode 100644 (file)
index 0000000..b182f57
--- /dev/null
+++ b/docs/compatible_configs.md
@@ -0,0 +1,261 @@
+# _Black_ compatible configurations
+
+All of Black's changes are harmless (or at least, they should be), but a few do conflict
+against other tools. It is not uncommon to be using other tools alongside _Black_ like
+linters and type checkers. Some of them need a bit of tweaking to resolve the conflicts.
+Listed below are _Black_ compatible configurations in various formats for the common
+tools out there.
+
+## isort
+
+[isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
+_Black_ also formats imports, but in a different way from isort's defaults which leads
+to conflicting changes.
+
+### Configuration
+
+```
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+```
+
+### Why those options above?
+
+_Black_ wraps imports that surpass `line-length` by moving identifiers into their own
+indented line. If that still doesn't fit the bill, it will put all of them in seperate
+lines and put a trailing comma. A more detailed explanation of this behaviour can be
+[found here](https://github.com/psf/black#how-black-wraps-lines).
+
+isort's default mode of wrapping imports that extend past the `line_length` limit is
+"Grid".
+
+```py3
+from third_party import (lib1, lib2, lib3,
+                         lib4, lib5, ...)
+```
+
+This style is incompatible with _Black_, but isort can be configured to use a different
+wrapping mode called "Vertical Hanging Indent" which looks like this:
+
+```py3
+from third_party import (
+    lib1,
+    lib2,
+    lib3,
+    lib4,
+)
+```
+
+This style is _Black_ compatible and can be achieved by `multi-line-output = 3`. Also,
+as mentioned above, when wrapping long imports _Black_ puts a trailing comma and uses
+parentheses. isort should follow the same behaviour and passing the options
+`include_trailing_comma = True` and `use_parentheses = True` configures that.
+
+The option `force_grid_wrap = 0` is just to tell isort to only wrap imports that surpass
+the `line_length` limit.
+
+Finally, isort should be told to wrap imports when they surpass _Black_'s default limit
+of 88 characters via `line_length = 88`.
+
+### Formats
+
+<details>
+<summary>.isort.cfg</summary>
+
+```cfg
+[settings]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+```
+
+</details>
+
+<details>
+<summary>setup.cfg</summary>
+
+```cfg
+[isort]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+```
+
+</details>
+
+<details>
+<summary>pyproject.toml</summary>
+
+```toml
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+```
+
+</details>
+
+<details>
+<summary>.editorconfig</summary>
+
+```ini
+[*.py]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+```
+
+</details>
+
+## Flake8
+
+[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
+[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, W503
+```
+
+### Why those options above?
+
+When breaking a line, _Black_ will break it before a binary operator. This is compliant
+with PEP 8, but this behaviour will cause flake8 to raise
+`W503 line break before binary operator` warnings.
+
+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 both of these warnings are not PEP 8 compliant, Flake8 should be configured to
+ignore these warnings via `extend-ignore = E203, W503`.
+
+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`.
+
+### Formats
+
+<details>
+<summary>.flake8</summary>
+
+```ini
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+```
+
+</details>
+
+<details>
+<summary>setup.cfg</summary>
+
+```cfg
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+```
+
+</details>
+
+<details>
+<summary>tox.ini</summary>
+
+```ini
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+```
+
+</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.
+
+### Configuration
+
+```
+disable = C0330, C0326
+max-line-length = 88
+```
+
+### Why those options above?
+
+When _Black_ is folding very long expressions, the closing brackets will
+[be dedented](https://github.com/psf/black#how-black-wraps-lines).
+
+```py3
+ImportantClass.important_method(
+    exc, limit, lookup_lines, capture_locals, callback
+)
+```
+
+Although, this style is PEP 8 compliant, Pylint will raise
+`C0330: Wrong hanging indentation before block (add 4 spaces)` warnings. Since _Black_
+isn't configurable on this style, Pylint should be told to ignore these warnings via
+`disable = C0330`.
+
+Also, since _Black_ deals with whitespace around operators and brackets, Pylint's
+warning `C0326: Bad whitespace` should be disabled using `disable = C0326`.
+
+And as usual, Pylint should be configured to only complain about lines that surpass `88`
+characters via `max-line-length = 88`.
+
+### Formats
+
+<details>
+<summary>pylintrc</summary>
+
+```rc
+[MESSAGES CONTROL]
+disable = C0330, C0326
+
+[format]
+max-line-length = 88
+```
+
+</details>
+
+<details>
+<summary>setup.cfg</summary>
+
+```cfg
+[pylint]
+max-line-length = 88
+
+[pylint.messages_control]
+disable = C0330, C0326
+```
+
+</details>
+
+<details>
+<summary>pyproject.toml</summary>
+
+```toml
+[tool.pylint.messages_control]
+disable = "C0330, C0326"
+
+[tool.pylint.format]
+max-line-length = "88"
+```
+
+</details>