]> 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 07bf672f4fd38d4d9aaa17c9ee2d32c9b6048eec..74c6a283ab8654e9ee0ff90b1c03da63da180879 100644 (file)
@@ -10,6 +10,19 @@ 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
@@ -46,6 +59,99 @@ Options include the following:
    - In `Trigger Settings` section of plugin configuration check
      `Trigger when saving changed files`.
 
+### As external tool
+
+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. Open External tools in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> External Tools`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> External Tools`
+
+1. Click the + icon to add a new external tool with the following values:
+
+   - Name: Black
+   - Description: Black is the uncompromising Python code formatter.
+   - Program: \<install_location_from_step_2>
+   - Arguments: `"$FilePath$"`
+
+1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+
+   - Alternatively, you can set a keyboard shortcut by navigating to
+     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+
+### 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
 
 Wing IDE supports `black` via **Preference Settings** for system wide settings and
@@ -104,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):
 
 ```
@@ -133,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).
@@ -147,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
@@ -159,6 +307,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`:
 
 ```
@@ -174,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