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 88176e1aecb937e08867d7caad94d00b310431f3..ff563068e799aae4ca12561cc74cfa487ae6c17f 100644 (file)
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,6 +10,57 @@ 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
+   $ pip install 'black[d]'
+   ```
+
+1. Install
+   [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
+
+1. Open plugin configuration in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> BlackConnect`
+
+1. In `Local Instance (shared between projects)` section:
+
+   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. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.
+
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.
+
+1. Optionally, to run _Black_ on every file save:
+
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
+
+### As external tool
+

 1. Install `black`.
 
    ```console
 1. Install `black`.
 
    ```console


@@ -57,29 +108,7 @@ Options include the following:
    - Alternatively, you can set a keyboard shortcut by navigating to
      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
 
    - Alternatively, you can set a keyboard shortcut by navigating to
      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
 

-1. Optionally, 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"
-
-## Wing IDE
-
-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:
+### As file watcher

 
 1. Install `black`.
 
 
 1. Install `black`.
 


@@ -87,27 +116,89 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
    $ pip install black
    ```
 
    $ pip install black
    ```
 

-1. Make sure it runs from the command line, e.g.
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:

 
    ```console
 
    ```console

-   $ black --help
+   $ which black
+   /usr/local/bin/black  # possible location

    ```
 
    ```
 

-1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
-   execute black on the currently selected file:
+   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
+**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:
+
+### Prerequistes
+
+- Wing IDE version 8.0+
+
+- Install `black`.
+
+  ```console
+  $ pip install black
+  ```

 
 

-   - 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
+- Make sure it runs from the command line, e.g.

 
 

-1. Select a file in the editor and press **F1** , or whatever key binding you selected
-   in step 3, to reformat the file.
+  ```console
+  $ black --help
+  ```
+
+### Preference Settings
+
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
+
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
+
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
+
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
+
+### Project Properties
+
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
+
+1. In menubar navigate to `Project -> Project Properties -> Options`.
+
+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
 
 
 ## Vim
 


@@ -116,23 +207,61 @@ 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);
 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;
 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;

-- `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
+- `:BlackVersion` to get the current version of _Black_ in use.

 
 Configuration:
 
 - `g:black_fast` (defaults to `0`)
 - `g:black_linelength` (defaults to `88`)
 - `g:black_skip_string_normalization` (defaults to `0`)
 
 Configuration:
 
 - `g:black_fast` (defaults to `0`)
 - `g:black_linelength` (defaults to `88`)
 - `g:black_skip_string_normalization` (defaults to `0`)

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

 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)

+- `g:black_use_virtualenv` (defaults to `1`)
+- `g:black_target_version` (defaults to `""`)

 - `g:black_quiet` (defaults to `0`)
 - `g:black_quiet` (defaults to `0`)

+- `g:black_preview` (defaults to `0`)
+
+#### Installation
+
+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.
+
+##### `vim-plug`

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

+_Black_'s `stable` branch tracks official version updates, and can be used to simply
+follow the most recent stable version.
+

 ```
 Plug 'psf/black', { 'branch': 'stable' }
 ```
 
 ```
 Plug 'psf/black', { 'branch': 'stable' }
 ```
 

+Another option which is a bit more explicit and offers more control is to use
+`vim-plug`'s `tag` option with a shell wildcard. This will resolve to the latest tag
+which matches the given pattern.
+
+The following matches all stable versions (see the
+[Release Process](../contributing/release_process.md) section for documentation of
+version scheme used by Black):
+
+```
+Plug 'psf/black', { 'tag': '*.*.*' }
+```
+
+and the following demonstrates pinning to a specific year's stable style (2022 in this
+case):
+
+```
+Plug 'psf/black', { 'tag': '22.*.*' }
+```
+
+##### Vundle
+

 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```


@@ -146,20 +275,29 @@ $ cd ~/.vim/bundle/black
 $ git checkout origin/stable -b stable
 ```
 
 $ git checkout origin/stable -b stable
 ```
 

-or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
+##### Arch Linux
+
+On Arch Linux, the plugin is shipped with the
+[`python-black`](https://archlinux.org/packages/community/any/python-black/) package, so
+you can start using it in Vim after install with no additional setup.
+
+##### Vim 8 Native Plugin Management
+
+or you can copy the plugin files from
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
+[autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).

 
 ```
 mkdir -p ~/.vim/pack/python/start/black/plugin
 
 ```
 mkdir -p ~/.vim/pack/python/start/black/plugin

+mkdir -p ~/.vim/pack/python/start/black/autoload

 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim

+curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim

 ```
 
 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
-be able to run _Black_ inside the Vim process which is much faster than calling an
-external command.
+#### Usage

 
 On first run, the plugin creates its own virtualenv using the right Python version and
 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
 
 On first run, the plugin creates its own virtualenv using the right Python version and
 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and


@@ -169,70 +307,31 @@ 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.
 
 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`:
+If you would prefer to use the system installation of _Black_ rather than a virtualenv,
+then add this to your vimrc:

 
 ```
 
 ```

-autocmd BufWritePre *.py execute ':Black'
+let g:black_use_virtualenv = 0

 ```
 
 ```
 

-To run _Black_ on a key press (e.g. F9 below), add this:
+Note that the `:BlackUpgrade` command is only usable and useful with a virtualenv, so
+when the virtualenv is not in use, `:BlackUpgrade` is disabled. If you need to upgrade
+the system installation of _Black_, then use your system package manager or pip--
+whatever tool you used to install _Black_ originally.

 
 

-```
-nnoremap <F9> :Black<CR>
-```
+To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:

 
 

-**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` 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.
-
-The two packages that cause the problem are:
-
-- [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
+augroup black_on_save
+  autocmd!
+  autocmd BufWritePre *.py Black
+augroup end

 ```
 
 ```
 

-And now you can install them with:
+To run _Black_ on a key press (e.g. F9 below), add this:

 
 

-```console
-$ pip install --no-binary :all: regex 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 regex,typed-ast
+nnoremap <F9> :Black<CR>

 ```
 
 ### With ALE
 ```
 
 ### With ALE


@@ -280,24 +379,26 @@ 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
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
 ## SublimeText 3
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 

-## Jupyter Notebook Magic
-
-Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
-
-## Python Language Server
+## Python LSP Server

 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 Sublime Text, Visual Studio Code and many more), you can use the
 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 Sublime Text, Visual Studio Code and many more), you can use the

-[Python Language Server](https://github.com/palantir/python-language-server) with the
-[pyls-black](https://github.com/rupert/pyls-black) plugin.
+[Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
+[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.

 
 ## Atom/Nuclide
 
 
 ## Atom/Nuclide