]> 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
Exclude pytest-xdist 3.0.2 (#3356)
[etc/vim.git] / docs / integrations / editors.md
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 9c279564fa3743c2aabe9a238523856788cf7435..28c9f48a09f29284304bb10e7baff1fe33c8eab5 100644 (file)
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,104 +10,89 @@ 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:
+1. Open plugin configuration in PyCharm/IntelliJ IDEA
 
 
-   ```console
-   $ which black
-   /usr/local/bin/black  # possible location
-   ```
+   On macOS:
 
 
-   On Windows:
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
 
 
-   ```console
-   $ where black
-   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
-   ```
+   On Windows / Linux / BSD:
 
 
-   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`.
+   `File -> Settings -> Tools -> BlackConnect`
 
 
-1. Open External tools in PyCharm/IntelliJ IDEA
+1. In `Local Instance (shared between projects)` section:
 
 
-   On macOS:
+   1. Check `Start local blackd instance when plugin loads`.
+   1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+      executable.
 
 
-   `PyCharm -> Preferences -> Tools -> External Tools`
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.
 
 
-   On Windows / Linux / BSD:
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.
+
+1. Optionally, to run _Black_ on every file save:
 
 
-   `File -> Settings -> Tools -> External Tools`
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
 
 
-1. Click the + icon to add a new external tool with the following values:
+## Wing IDE
 
 
-   - Name: Black
-   - Description: Black is the uncompromising Python code formatter.
-   - Program: \<install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+Wing IDE supports `black` via **Preference Settings** for system wide settings and
+**Project Properties** for per-project or workspace specific settings, as explained in
+the Wing documentation on
+[Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
+procedure is:
 
 
-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+### Prerequistes
 
 
-   - Alternatively, you can set a keyboard shortcut by navigating to
-     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+- Wing IDE version 8.0+
 
 
-1. Optionally, run _Black_ on every file save:
+- Install `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$`
+  ```console
+  $ pip install black
+  ```
 
 
-   - In Advanced Options
-     - Uncheck "Auto-save edited files to trigger the watcher"
-     - Uncheck "Trigger the watcher on external changes"
+- Make sure it runs from the command line, e.g.
 
 
-## Wing IDE
+  ```console
+  $ black --help
+  ```
 
 
-Wing supports black via the OS Commands tool, as explained in the Wing documentation on
-[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
+### Preference Settings
 
 
-1. Install `black`.
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
 
 
-   ```console
-   $ pip install black
-   ```
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
 
 
-1. Make sure it runs from the command line, e.g.
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
 
 
-   ```console
-   $ black --help
-   ```
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
+
+### Project Properties
 
 
-1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
-   execute black on the currently selected file:
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
 
 
-   - Use the Tools -> OS Commands menu selection
-   - click on **+** in **OS Commands** -> New: Command line..
-     - Title: black
-     - Command Line: black %s
-     - I/O Encoding: Use Default
-     - Key Binding: F1
-     - [x] Raise OS Commands when executed
-     - [x] Auto-save files before execution
-     - [x] Line mode
+1. In menubar navigate to `Project -> Project Properties -> Options`.
 
 
-1. Select a file in the editor and press **F1** , or whatever key binding you selected
-   in step 3, to reformat the file.
+1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
+   or `Whole files before save`.
+
+1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
 
 ## Vim
 
 
 ## Vim
 
@@ -128,6 +113,7 @@ Configuration:
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_quiet` (defaults to `0`)
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_quiet` (defaults to `0`)
+- `g:black_preview` (defaults to `0`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
@@ -162,7 +148,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
+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.
 
 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.
 
@@ -174,10 +160,13 @@ 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.
 
-To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
+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:
 ```
 
 To run _Black_ on a key press (e.g. F9 below), add this:
@@ -283,9 +272,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.