Add formatter to README

README.md

@@ -6,8 +6,11 @@
 [![image](https://img.shields.io/pypi/pyversions/ruff/0.0.292.svg)](https://pypi.python.org/pypi/ruff)
 [![Actions status](https://github.com/astral-sh/ruff-vscode/workflows/CI/badge.svg)](https://github.com/astral-sh/ruff-vscode/actions)
 
-A Visual Studio Code extension with support for the [Ruff](https://github.com/astral-sh/ruff)
-linter. Available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff).
+A Visual Studio Code extension for [Ruff](https://github.com/astral-sh/ruff), an extremely fast
+Python linter and code formatter, written in Rust. Available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff).
+
+Ruff can be used to replace Flake8 (plus dozens of plugins), Black, isort, pyupgrade, and more,
+all while executing tens or hundreds of times faster than any individual tool.
 
 The extension ships with `ruff==0.0.292`.
 
@@ -18,15 +21,19 @@ The extension ships with `ruff==0.0.292`.
 
 ### "Quick Fix" actions for auto-fixable violations (like unused imports)
 
-![Demo of Ruff's "Quick Fix" action](https://user-images.githubusercontent.com/1309177/205176932-44cfc03a-120f-4bad-b710-612bdd7765d6.gif)
+![Using the "Quick Fix" action to fix a violation](https://user-images.githubusercontent.com/1309177/205176932-44cfc03a-120f-4bad-b710-612bdd7765d6.gif)
 
 ### "Fix all": automatically fix all auto-fixable violations
 
-![Demo of Ruff's "Fix all" action](https://user-images.githubusercontent.com/1309177/205175763-cf34871d-5c05-4abf-9916-440afc82dbf8.gif)
+![Using the "Fix all" action to fix all violations](https://user-images.githubusercontent.com/1309177/205175763-cf34871d-5c05-4abf-9916-440afc82dbf8.gif)
+
+### "Format Document": Black-compatible code formatting
+
+![Using the "Format Document" action to format Python source code](https://github.com/astral-sh/ruff-lsp/assets/1309177/51c27215-87fb-490c-b1d6-ee81ab4171a1)
 
 ### "Organize Imports": `isort`-compatible import sorting
 
-![Demo of Ruff's "Organize Imports" action](https://user-images.githubusercontent.com/1309177/205175987-82e23e21-14bb-467d-9ef0-027f24b75865.gif)
+![Using the "Organize Imports" action to sort and deduplicate Python imports](https://user-images.githubusercontent.com/1309177/205175987-82e23e21-14bb-467d-9ef0-027f24b75865.gif)
 
 ## Usage
 
@@ -64,7 +71,19 @@ safety works.
 
 ### Example configurations
 
-You can configure Ruff to autofix violations on-save by enabling the `source.fixAll` action in
+You can configure Ruff to format Python code on-save by enabling the `editor.formatOnSave` action in
+`settings.json`, and setting Ruff as your default formatter:
+
+```json
+{
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}
+```
+
+You can configure Ruff to fix lint violations on-save by enabling the `source.fixAll` action in
 `settings.json`:
 
 ```json
@@ -77,8 +96,8 @@ You can configure Ruff to autofix violations on-save by enabling the `source.fix
 }
 ```
 
-You can configure Ruff to organize imports on-save by enabling the `source.organizeImports` action in
-`settings.json`:
+Similarly, you can configure Ruff to organize imports on-save by enabling the
+`source.organizeImports` action in `settings.json`:
 
 ```json
 {
@@ -90,9 +109,24 @@ You can configure Ruff to organize imports on-save by enabling the `source.organ
 }
 ```
 
+Taken together, you can configure Ruff to format, fix, and organize imports on-save via the
+following `settings.json`:
+
+```json
+{
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll": true,
+      "source.organizeImports": true
+    },
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}
+```
+
 If you're using the [VS Code Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python),
-you can configure VS Code to autofix violations on-save using Ruff,
-then re-format with [the Black extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter),
+you can configure VS Code to fix violations on-save using Ruff, then re-format with [the Black extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter),
 via the following `settings.json`:
 
 ```json
@@ -107,9 +141,8 @@ via the following `settings.json`:
 }
 ```
 
-If you'd like to use Ruff as an autofix linter, but continue to sort imports with the `isort` VS
-Code extension, you can disable Ruff's import-sorting capabilities via the following
-`settings.json`:
+If you'd like to use Ruff as a linter, but continue to sort imports with the [isort extension](https://marketplace.visualstudio.com/items?itemName=ms-python.isort),
+you can disable Ruff's import-sorting capabilities via the following `settings.json`:
 
 ```json
 {
@@ -123,7 +156,7 @@ Code extension, you can disable Ruff's import-sorting capabilities via the follo
 }
 ```
 
-If you'd like to run Ruff on-save, but avoid enabling other extensions to run on-save, you can
+If you'd like to run Ruff on-save, but avoid allowing other extensions to run on-save, you can
 use Ruff's scoped `source.fixAll` and `source.organizeImports` actions via the following `settings.json`:
 
 ```json
@@ -137,8 +170,8 @@ use Ruff's scoped `source.fixAll` and `source.organizeImports` actions via the f
 }
 ```
 
-If you'd like to run Ruff in lieu of another formatter altogether, be sure to unset the
-`editor.defaultFormatter` in `settings.json`:
+If you'd like to run Ruff, but disable code formatting (by Ruff, or by another formatter), be sure
+to unset the `editor.defaultFormatter` in `settings.json`:
 
 ```json
 {