X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/fdb01f8622de9394fe9d8ee149985d365ca1419f..29dd25725303992d36c3a75c3a071080ac06085f:/docs/integrations/editors.md?ds=sidebyside
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 02baa29..a8b7978 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,71 +10,41 @@ 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:
-
- ```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:
- `PyCharm -> Preferences -> Tools -> External Tools`
+ `PyCharm -> Preferences -> Tools -> BlackConnect`
On Windows / Linux / BSD:
- `File -> Settings -> Tools -> External Tools`
-
-1. Click the + icon to add a new external tool with the following values:
+ `File -> Settings -> Tools -> BlackConnect`
- - Name: Black
- - Description: Black is the uncompromising Python code formatter.
- - Program: \<install_location_from_step_2>
- - Arguments: `"$FilePath$"`
+1. In `Local Instance (shared between projects)` section:
-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+ 1. Check `Start local blackd instance when plugin loads`.
+ 1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+ executable.
- - Alternatively, you can set a keyboard shortcut by navigating to
- `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+ reformatting with _Black_.
-1. Optionally, run _Black_ on every file save:
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+ shortcut.
- 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$`
+1. Optionally, to run _Black_ on every file save:
- - 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
@@ -134,22 +104,58 @@ Commands and shortcuts:
- 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.
+- `: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`)
+- `g:black_skip_magic_trailing_comma` (defaults to `0`)
- `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_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):
+_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' }
```
+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):
```
@@ -163,6 +169,14 @@ $ cd ~/.vim/bundle/black
$ git checkout origin/stable -b stable
```
+##### 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).
@@ -177,9 +191,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.
-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
@@ -189,6 +201,18 @@ 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.
+If you would prefer to use the system installation of _Black_ rather than a virtualenv,
+then add this to your vimrc:
+
+```
+let g:black_use_virtualenv = 0
+```
+
+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.
+
To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
```
@@ -204,6 +228,8 @@ To run _Black_ on a key press (e.g. F9 below), add this:
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