]> git.madduck.net Git - etc/vim.git/blobdiff - docs/integrations/editors.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Bump peter-evans/create-or-update-comment from 3.0.1 to 3.0.2 (#3730)
[etc/vim.git] / docs / integrations / editors.md
index 5d2f83ace8aa6f512df26006fba69fa0e61a1d70..74c6a283ab8654e9ee0ff90b1c03da63da180879 100644 (file)
@@ -10,6 +10,57 @@ Options include the following:
 
 ## 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
@@ -57,24 +108,49 @@ Options include the following:
    - 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"
+### 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
 
@@ -134,22 +210,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 +275,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 +297,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,10 +307,25 @@ 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`:
+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`:
 
 ```
-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:
@@ -201,6 +334,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
@@ -298,9 +433,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