X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/8b0c7bcfda60e2200ce1335b5b371593548ab9f8..59acf8af38a72e57b26d739adb5d5e7f350e8f2c:/docs/integrations/editors.md

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 6098631..07bf672 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,104 +10,89 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
-1. Install `black`.
+1. Install _Black_ with the `d` extra.
 
    ```console
-   $ pip install black
+   $ pip install 'black[d]'
    ```
 
-1. Locate your `black` installation folder.
+1. Install
+   [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
 
-   On macOS / Linux / BSD:
+1. Open plugin configuration in PyCharm/IntelliJ IDEA
 
-   ```console
-   $ which black
-   /usr/local/bin/black  # possible location
-   ```
+   On macOS:
 
-   On Windows:
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
 
-   ```console
-   $ where black
-   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
-   ```
+   On Windows / Linux / BSD:
 
-   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`.
+   `File -> Settings -> Tools -> BlackConnect`
 
-1. Open External tools in PyCharm/IntelliJ IDEA
+1. In `Local Instance (shared between projects)` section:
 
-   On macOS:
+   1. Check `Start local blackd instance when plugin loads`.
+   1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+      executable.
 
-   `PyCharm -> Preferences -> Tools -> External Tools`
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.
 
-   On Windows / Linux / BSD:
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.
+
+1. Optionally, to run _Black_ on every file save:
 
-   `File -> Settings -> Tools -> External Tools`
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
 
-1. Click the + icon to add a new external tool with the following values:
+## Wing IDE
 
-   - Name: Black
-   - Description: Black is the uncompromising Python code formatter.
-   - Program: \<install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+Wing IDE supports `black` via **Preference Settings** for system wide settings and
+**Project Properties** for per-project or workspace specific settings, as explained in
+the Wing documentation on
+[Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
+procedure is:
 
-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+### Prerequistes
 
-   - Alternatively, you can set a keyboard shortcut by navigating to
-     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+- Wing IDE version 8.0+
 
-1. Optionally, run _Black_ on every file save:
+- Install `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$`
+  ```console
+  $ pip install black
+  ```
 
-   - In Advanced Options
-     - Uncheck "Auto-save edited files to trigger the watcher"
-     - Uncheck "Trigger the watcher on external changes"
+- Make sure it runs from the command line, e.g.
 
-## Wing IDE
+  ```console
+  $ black --help
+  ```
 
-Wing supports black via the OS Commands tool, as explained in the Wing documentation on
-[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
+### Preference Settings
 
-1. Install `black`.
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
 
-   ```console
-   $ pip install black
-   ```
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
 
-1. Make sure it runs from the command line, e.g.
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
 
-   ```console
-   $ black --help
-   ```
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
+
+### Project Properties
 
-1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
-   execute black on the currently selected file:
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
 
-   - Use the Tools -> OS Commands menu selection
-   - click on **+** in **OS Commands** -> New: Command line..
-     - Title: black
-     - Command Line: black %s
-     - I/O Encoding: Use Default
-     - Key Binding: F1
-     - [x] Raise OS Commands when executed
-     - [x] Auto-save files before execution
-     - [x] Line mode
+1. In menubar navigate to `Project -> Project Properties -> Options`.
 
-1. Select a file in the editor and press **F1** , or whatever key binding you selected
-   in step 3, to reformat the file.
+1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
+   or `Whole files before save`.
+
+1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
 
 ## Vim
 
@@ -116,6 +101,8 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
 Commands and shortcuts:
 
 - `:Black` to format the entire file (ranges not supported);
+  - you can optionally pass `target_version=<version>` with the same values as in the
+    command line.
 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 
@@ -172,10 +159,13 @@ If you need to do anything special to make your virtualenv work and install _Bla
 example you want to run a version from main), create a virtualenv manually and point
 `g:black_virtualenv` to it. The plugin will use it.
 
-To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
+To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 
 ```
-autocmd BufWritePre *.py execute ':Black'
+augroup black_on_save
+  autocmd!
+  autocmd BufWritePre *.py Black
+augroup end
 ```
 
 To run _Black_ on a key press (e.g. F9 below), add this:
@@ -202,30 +192,28 @@ Traceback (most recent call last):
 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` and `regex` 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.
+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 two packages that cause the problem are:
+The package that causes problems is:
 
-- [regex](https://pypi.org/project/regex/)
 - [typed-ast](https://pypi.org/project/typed-ast/)
 
 Now remove those two packages:
 
 ```console
-$ pip uninstall regex typed-ast -y
+$ pip uninstall typed-ast -y
 ```
 
 And now you can install them with:
 
 ```console
-$ pip install --no-binary :all: regex typed-ast
+$ pip install --no-binary :all: typed-ast
 ```
 
 The C extensions will be compiled and now Vim's Python environment will match. Note that
@@ -235,7 +223,7 @@ 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 regex,typed-ast
+$ pip install -U black --no-binary typed-ast
 ```
 
 ### With ALE
@@ -283,9 +271,15 @@ close and reopen your File, _Black_ will be done with its job.
 
 ## Visual Studio Code
 
-Use the
-[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
+- Use the
+  [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
+
+- Alternatively the pre-release
+  [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
+  extension can be used which runs a [Language Server Protocol](https://langserver.org/)
+  server for Black. Formatting is much more responsive using this extension, **but the
+  minimum supported version of Black is 22.3.0**.
 
 ## SublimeText 3