From a334c69e05637d41e2f9516845ea4f38b7993d97 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Mon, 22 Jul 2024 18:59:42 +0900
Subject: [PATCH] Add instructions for configuring linting in the Python
 documentation using Ruff extension (#14896)

Added documentation for #14198

I also suggest replacing format guides from `black` to `ruff` to unify
the tooling in the document.

Ruff is now widely used in the Python community, including
[fastapi](https://github.com/tiangolo/fastapi/blob/cd6e9db0653eabbf0fb14908c73939a11a131058/pyproject.toml#L213).
It's compatible with black but a lot faster.

Release Notes:

- N/A
---
 docs/src/languages/python.md | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/docs/src/languages/python.md b/docs/src/languages/python.md
index 765b15a09a57e5cd40612f0bf9c54eb176e90db5..99f28077dcda50837db1e808fae687e866d32130 100644
--- a/docs/src/languages/python.md
+++ b/docs/src/languages/python.md
@@ -16,6 +16,7 @@ For more information, see the Pyright [configuration documentation](https://micr
 The [pyright](https://github.com/microsoft/pyright) language server also accepts specific LSP related settings, not necessarily connected to a project. These can be changed in the `lsp` section of your `settings.json`.
 
 For example, in order to:
+
 - use strict type-checking level
 - diagnose all files in the workspace instead of the only open files default
 - provide the path to a specific python interpreter
@@ -93,23 +94,30 @@ You can also configure this option directly in your `settings.json` file ([pyrig
 }
 ```
 
-### Code formatting
+### Code formatting & Linting
+
+The Pyright language server does not provide code formatting or linting. If you want to detect lint errors and reformat your Python code upon saving, you'll need to set up.
 
-The Pyright language server does not provide code formatting. If you want to automatically reformat your Python code when saving, you'll need to specify an \_external_code formatter in your settings. See the [configuration](../configuring-zed.md) documentation for more information.
+A common tool for formatting Python code is [Ruff](https://black.readthedocs.io/en/stable/). It is another tool written in Rust, an extremely fast Python linter and code formatter.
 
-A common tool for formatting python code is [Black](https://black.readthedocs.io/en/stable/). If you have Black installed globally, you can use it to format Python files by adding the following to your `settings.json`:
+It is available through the [Ruff extension](https://docs.astral.sh/ruff/). However, the code formatting through the extension is not yet available. You can set up the formatter to run on save by adding the following configuration to your `settings.json`, assuming that [`Ruff`](https://docs.astral.sh/ruff/) is installed in your Python environment.
 
 ```json
 {
   "languages": {
+    ..., // other languages
     "Python": {
-      "formatter": {
-         "external": {
-          "command": "black",
-          "arguments": ["-"]
+      "format_on_save": {
+        "external": {
+          "command": "python",
+          "arguments": [
+            "-m",
+            "ruff",
+            "format",
+            "-"
+          ]
         }
-      },
-      "format_on_save": "on"
+      }
     }
   }
 }