]> 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:

projects / etc / vim.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Bump pypa/cibuildwheel from 2.11.3 to 2.11.4 (#3475)
[etc/vim.git] / docs / integrations / editors.md
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 1c7879b63a6a189cf0c99190eaa111e8842fb15e..a8b7978c4d788919f14fbe0dc3575a9d241437a2 100644 (file)
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,71 +10,41 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
 
 ## PyCharm/IntelliJ IDEA
 
-1. Install `black`.
+1. Install _Black_ with the `d` extra.
 
    ```console
 
    ```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:
 
 
    On macOS:
 
-   `PyCharm -> Preferences -> Tools -> External Tools`
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
 
    On Windows / Linux / BSD:
 
 
    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
 
 
 ## 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;
   - 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`)
 
 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):
 
 ```
@@ -163,6 +169,14 @@ $ cd ~/.vim/bundle/black
 $ git checkout origin/stable -b stable
 ```
 
 $ 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).
 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.
 
 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
@@ -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.
 
 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`:
 
 ```
 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>
 ```
 
 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
 **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
@@ -301,9 +327,15 @@ 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
 
 
 ## SublimeText 3
 
vim configuration

Legalese

All content available in this repository is copyright © martin f. krafft, unless otherwise noted.

All files and their content are released under the terms of the Artistic Licence 2.0, unless otherwise noted.

The operator of this repository shall not be held liable for offending content in pages linking to or linked from these page, nor does he endorse their content unless stated otherwise.