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

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 83429d7437f7bb7716ad1b1ad23afd92d51f57c2..43d47fc6dfabbaa10170ecaaf84f524d6031eb5a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ Try it out now using the [Black Playground](https://black.now.sh). Watch the
 ---
 
 _Contents:_ **[Installation and usage](#installation-and-usage)** |
-**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)**
+**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)** |
 **[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** |
 **[blackd](#blackd)** | **[Version control integration](#version-control-integration)**
 | **[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)**
@@ -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
@@ -497,7 +507,7 @@ there were not many users anyway. Not many edge cases were reported. As a mature
 _Black_ does make some exceptions to rules it otherwise holds. This section documents
 what those exceptions are and why this is the case.
 
-### The magic trailling comma
+### The magic trailing comma
 
 _Black_ in general does not take existing formatting into account.
 
@@ -648,6 +658,9 @@ $ where black
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 
+Note that if you are using a virtual environment detected by PyCharm, this is an
+unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
 3. Open External tools in PyCharm/IntelliJ IDEA
 
 On macOS:
@@ -738,7 +751,7 @@ Configuration:
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
-Plug 'psf/black'
+Plug 'psf/black', { 'branch': 'stable' }
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
@@ -747,8 +760,15 @@ or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 Plugin 'psf/black'
 ```
 
+and execute the following in a terminal:
+
+```console
+$ cd ~/.vim/bundle/black
+$ git checkout origin/stable -b stable
+```
+
 or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/tree/master/plugin/black.vim).
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
 
 ```
 mkdir -p ~/.vim/pack/python/start/black/plugin
@@ -978,6 +998,8 @@ code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy
 Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
 Agent Integration, Home Assistant.
 
+The following organizations use _Black_: Dropbox.
+
 Are we missing anyone? Let us know.
 
 ## Testimonials
@@ -1056,7 +1078,7 @@ Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
 
 Multiple contributions by:
 
-- [Abdur-Rahmaan Janhangeer](mailto:cryptolabour@gmail.com)
+- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
 - [Adam Johnson](mailto:me@adamj.eu)
 - [Alexander Huynh](mailto:github@grande.coffee)
 - [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)