Preserve crlf line endings in blackd (#3257)

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

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 1c7879b63a6a189cf0c99190eaa111e8842fb15e..28c9f48a09f29284304bb10e7baff1fe33c8eab5 100644 (file)
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,71 +10,41 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
 
 ## PyCharm/IntelliJ IDEA
 

-1. Install `black`.
+1. Install _Black_ with the `d` extra.

 
    ```console
 
    ```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:
-
-   ```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
+1. Open plugin configuration in PyCharm/IntelliJ IDEA

 
    On macOS:
 
 
    On macOS:
 

-   `PyCharm -> Preferences -> Tools -> External Tools`
+   `PyCharm -> Preferences -> Tools -> BlackConnect`

 
    On Windows / Linux / BSD:
 
 
    On Windows / Linux / BSD:
 

-   `File -> Settings -> Tools -> External Tools`
+   `File -> Settings -> Tools -> BlackConnect`

 
 

-1. Click the + icon to add a new external tool with the following values:
+1. In `Local Instance (shared between projects)` section:

 
 

-   - Name: Black
-   - Description: Black is the uncompromising Python code formatter.
-   - Program: \<install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+   1. Check `Start local blackd instance when plugin loads`.
+   1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+      executable.

 
 

-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.

 
 

-   - Alternatively, you can set a keyboard shortcut by navigating to
-     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.

 
 

-1. Optionally, run _Black_ on every file save:
+1. Optionally, to run _Black_ on every file save:

 
 

-   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"
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.

 
 ## Wing IDE
 
 
 ## Wing IDE
 


@@ -143,6 +113,7 @@ Configuration:
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_quiet` (defaults to `0`)
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_quiet` (defaults to `0`)

+- `g:black_preview` (defaults to `0`)

 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 


@@ -177,7 +148,7 @@ curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/
 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 Pathogen, and so on.
 
 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 Pathogen, and so on.
 

-This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
+This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to

 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.
 
 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.
 


@@ -301,9 +272,15 @@ close and reopen your File, _Black_ will be done with its job.
 
 ## Visual Studio Code
 
 
 ## 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
 
 
 ## SublimeText 3