]> 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 furo from 2022.6.21 to 2022.9.15 in /docs (#3277)
[etc/vim.git] / docs / integrations / editors.md
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index dd09b4df6d1a84f2fe8a749b637792ead10f5b11..318e0e295d0567481cf9738e3f0680c058a9194d 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.
 
 
-   `File -> Settings -> Tools -> External Tools`
+1. Optionally, to run _Black_ on every file save:
 
 
-1. Click the + icon to add a new external tool with the following values:
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
 
 
-   - Name: Black
-   - Description: Black is the uncompromising Python code formatter.
-   - Program: \<install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+## Wing IDE
 
 
-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+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:
 
 
-   - Alternatively, you can set a keyboard shortcut by navigating to
-     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+### Prerequistes
 
 
-1. Optionally, run _Black_ on every file save:
+- Wing IDE version 8.0+
 
 
-   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$`
+- Install `black`.
 
 
-   - In Advanced Options
-     - Uncheck "Auto-save edited files to trigger the watcher"
-     - Uncheck "Trigger the watcher on external changes"
+  ```console
+  $ pip install black
+  ```
 
 
-## Wing IDE
+- Make sure it runs from the command line, e.g.
 
 
-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:
+  ```console
+  $ black --help
+  ```
 
 
-1. Install `black`.
+### Preference Settings
 
 
-   ```console
-   $ pip install black
-   ```
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
 
 
-1. Make sure it runs from the command line, e.g.
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
 
 
-   ```console
-   $ black --help
-   ```
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
+
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
 
 
-1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
-   execute black on the currently selected file:
+### Project Properties
 
 
-   - 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
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
 
 
-1. Select a file in the editor and press **F1** , or whatever key binding you selected
-   in step 3, to reformat the file.
+1. In menubar navigate to `Project -> Project Properties -> Options`.
+
+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
 
@@ -116,6 +101,8 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
 Commands and shortcuts:
 
 - `:Black` to format the entire file (ranges not supported);
 Commands and shortcuts:
 
 - `:Black` to format the entire file (ranges not supported);
+  - 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.
 
 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 
@@ -126,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):
 
@@ -172,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:
@@ -202,30 +193,28 @@ Traceback (most recent call last):
 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 ```
 
 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 ```
 
-Then you need to install `typed_ast` and `regex` directly from the source code. The
-error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
-they are available. Python wheels are a new standard of distributing Python packages and
-packages that have Cython and extensions written in C are already compiled, so the
-installation is much more faster. The problem here is that somehow the Python
-environment inside Vim does not match with those already compiled C extensions and these
-kind of errors are the result. Luckily there is an easy fix: installing the packages
-from the source code.
+Then you need to install `typed_ast` directly from the source code. The error happens
+because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
+available. Python wheels are a new standard of distributing Python packages and packages
+that have Cython and extensions written in C are already compiled, so the installation
+is much more faster. The problem here is that somehow the Python environment inside Vim
+does not match with those already compiled C extensions and these kind of errors are the
+result. Luckily there is an easy fix: installing the packages from the source code.
 
 
-The two packages that cause the problem are:
+The package that causes problems is:
 
 
-- [regex](https://pypi.org/project/regex/)
 - [typed-ast](https://pypi.org/project/typed-ast/)
 
 Now remove those two packages:
 
 ```console
 - [typed-ast](https://pypi.org/project/typed-ast/)
 
 Now remove those two packages:
 
 ```console
-$ pip uninstall regex typed-ast -y
+$ pip uninstall typed-ast -y
 ```
 
 And now you can install them with:
 
 ```console
 ```
 
 And now you can install them with:
 
 ```console
-$ pip install --no-binary :all: regex typed-ast
+$ pip install --no-binary :all: typed-ast
 ```
 
 The C extensions will be compiled and now Vim's Python environment will match. Note that
 ```
 
 The C extensions will be compiled and now Vim's Python environment will match. Note that
@@ -235,7 +224,7 @@ Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
 If you later want to update _Black_, you should do it like this:
 
 ```console
 If you later want to update _Black_, you should do it like this:
 
 ```console
-$ pip install -U black --no-binary regex,typed-ast
+$ pip install -U black --no-binary typed-ast
 ```
 
 ### With ALE
 ```
 
 ### With ALE
@@ -283,24 +272,26 @@ 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
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
 ## SublimeText 3
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
-## Jupyter Notebook Magic
-
-Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
-
-## Python Language Server
+## Python LSP Server
 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 Sublime Text, Visual Studio Code and many more), you can use the
 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 Sublime Text, Visual Studio Code and many more), you can use the
-[Python Language Server](https://github.com/palantir/python-language-server) with the
-[pyls-black](https://github.com/rupert/pyls-black) plugin.
+[Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
+[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
 
 ## Atom/Nuclide
 
 
 ## Atom/Nuclide
 
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.