X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/2189bcaac01d9b6289411a75557a23cf4a06b783..c9efbf9d97b65d67f6e87ee4b77bed0445bd7a9f:/docs/integrations/editors.md?ds=inline diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md index 28c9f48..74c6a28 100644 --- a/docs/integrations/editors.md +++ b/docs/integrations/editors.md @@ -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 `, 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: \ + - 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: \ + - 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,23 +210,58 @@ Commands and shortcuts: - you can optionally pass `target_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): ``` @@ -134,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). @@ -148,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.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. +#### 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 @@ -160,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`: ``` @@ -175,6 +334,8 @@ To run _Black_ on a key press (e.g. F9 below), add this: nnoremap :Black ``` +#### 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