Fix diff-shades comment missing newlines (#3799)

[etc/vim.git] / docs / integrations / editors.md

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index a8b7978c4d788919f14fbe0dc3575a9d241437a2..ff563068e799aae4ca12561cc74cfa487ae6c17f 100644 (file)
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,6 +10,19 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
 
 ## PyCharm/IntelliJ IDEA
 

+There are three different ways you can use _Black_ from PyCharm:
+
+1. As local server using the BlackConnect plugin
+1. As external tool
+1. As file watcher
+
+The first option is the simplest to set up and formats the fastest (by spinning up
+{doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, avoiding the
+startup cost on subsequent formats), but if you would prefer to not install a
+third-party plugin or blackd's extra dependencies, the other two are also great options.
+
+### As local server
+

 1. Install _Black_ with the `d` extra.
 
    ```console
 1. Install _Black_ with the `d` extra.
 
    ```console


@@ -46,6 +59,99 @@ Options include the following:
    - In `Trigger Settings` section of plugin configuration check
      `Trigger when saving changed files`.
 
    - In `Trigger Settings` section of plugin configuration check
      `Trigger when saving changed files`.
 

+### As external tool
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ 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`.
+
+1. Open External tools in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> External Tools`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> External Tools`
+
+1. Click the + icon to add a new external tool with the following values:
+
+   - Name: Black
+   - Description: Black is the uncompromising Python code formatter.
+   - Program: \<install_location_from_step_2>
+   - Arguments: `"$FilePath$"`
+
+1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+
+   - Alternatively, you can set a keyboard shortcut by navigating to
+     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+
+### As file watcher
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ 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`.
+
+1. Make sure you have the
+   [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
+   installed.
+1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new
+   watcher:
+   - Name: Black
+   - File type: Python
+   - Scope: Project Files
+   - Program: \<install_location_from_step_2>
+   - Arguments: `$FilePath$`
+   - Output paths to refresh: `$FilePath$`
+   - Working directory: `$ProjectFileDir$`
+
+- In Advanced Options
+  - Uncheck "Auto-save edited files to trigger the watcher"
+  - Uncheck "Trigger the watcher on external changes"
+

 ## Wing IDE
 
 Wing IDE supports `black` via **Preference Settings** for system wide settings and
 ## Wing IDE
 
 Wing IDE supports `black` via **Preference Settings** for system wide settings and


@@ -228,60 +334,6 @@ To run _Black_ on a key press (e.g. F9 below), add this:
 nnoremap <F9> :Black<CR>
 ```
 
 nnoremap <F9> :Black<CR>
 ```
 

-#### Troubleshooting
-
-**How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
-default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
-use: `./configure --enable-python3interp=yes`. There's many guides online how to do
-this.
-
-**I get an import error when using _Black_ from a virtual environment**: If you get an
-error message like this:
-
-```text
-Traceback (most recent call last):
-  File "<string>", line 63, in <module>
-  File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
-    from typed_ast import ast3, ast27
-  File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
-    from typed_ast import _ast3
-ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
-```
-
-Then you need to install `typed_ast` directly from the source code. The error happens
-because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
-available. Python wheels are a new standard of distributing Python packages and packages
-that have Cython and extensions written in C are already compiled, so the installation
-is much more faster. The problem here is that somehow the Python environment inside Vim
-does not match with those already compiled C extensions and these kind of errors are the
-result. Luckily there is an easy fix: installing the packages from the source code.
-
-The package that causes problems is:
-
-- [typed-ast](https://pypi.org/project/typed-ast/)
-
-Now remove those two packages:
-
-```console
-$ pip uninstall typed-ast -y
-```
-
-And now you can install them with:
-
-```console
-$ pip install --no-binary :all: typed-ast
-```
-
-The C extensions will be compiled and now Vim's Python environment will match. Note that
-you need to have the GCC compiler and the Python development files installed (on
-Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
-
-If you later want to update _Black_, you should do it like this:
-
-```console
-$ pip install -U black --no-binary typed-ast
-```
-

 ### With ALE
 
 1. Install [`ale`](https://github.com/dense-analysis/ale)
 ### With ALE
 
 1. Install [`ale`](https://github.com/dense-analysis/ale)