From 8f707653c2555cf2d466b951a9c76657a31cbaeb Mon Sep 17 00:00:00 2001
From: Xin Zhao <zx0@mail.ustc.edu.cn>
Date: Wed, 11 Feb 2026 16:33:41 +0800
Subject: [PATCH] docs: Update the formatting section for Python (#48904)

I have added the `code_actions_on_format` setting. I also temporarily
removed the mention of `"formatter": null`. Based on our findings in
#48600, its current behavior is inconsistent, so I've omitted it for now
to avoid confusing users. I will add it back once the underlying issue
is fixed (likely in a subsequent PR).

Closes #48600.

- [ ] Tests or screenshots needed?
- [x] Code Reviewed
- [x] Manual QA

Release Notes:

- N/A

---------

Co-authored-by: Kunall Banerjee <hey@kimchiii.space>
---
 docs/src/languages/python.md | 37 ++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/docs/src/languages/python.md b/docs/src/languages/python.md
index 9f019f84721812905113cf9e8c61203f2d0bdf43..bcce6ca123774c1c4aab2b92f7d7137f1b6fea09 100644
--- a/docs/src/languages/python.md
+++ b/docs/src/languages/python.md
@@ -190,35 +190,60 @@ For most projects, Zed will automatically select the right Python toolchain. In
 
 ## Code Formatting & Linting
 
-Zed provides the [Ruff](https://docs.astral.sh/ruff/) formatter and linter for Python code. (Specifically, Zed runs Ruff as an LSP server using the `ruff server` subcommand.) Both formatting and linting are enabled by default, including format-on-save.
+Zed uses [Ruff](https://github.com/astral-sh/ruff) for formatting and linting Python code. Specifically, it runs Ruff as an LSP server using the `ruff server` subcommand.
 
-### Configuring formatting
+### Configuring Formatting
 
-You can disable format-on-save for Python files in your `settings.json`:
+Formatting in Zed follows a two-phase pipeline: first, code actions on format (`code_actions_on_format`) are executed, followed by the configured formatter:
 
 ```json [settings]
 {
   "languages": {
     "Python": {
-      "format_on_save": "off"
+      "code_actions_on_format": {
+        "source.organizeImports.ruff": true
+      },
+      "formatter": {
+        "language_server": {
+          "name": "ruff"
+        }
+      }
     }
   }
 }
 ```
 
-Alternatively, you can use the `black` command-line tool for Python formatting, while keeping Ruff enabled for linting:
+These two phases are independent. For example, if you prefer [Black](https://github.com/psf/black) for code formatting, but want to keep Ruff's import sorting, you only need to change the formatter phase:
 
 ```json [settings]
 {
   "languages": {
     "Python": {
+      "code_actions_on_format": {
+        // Phase 1: Ruff still handles organize imports
+        "source.organizeImports.ruff": true
+      },
       "formatter": {
+        // Phase 2: Black handles formatting
         "external": {
           "command": "black",
           "arguments": ["--stdin-filename", "{buffer_path}", "-"]
         }
       }
-      // Or use `"formatter": null` to disable formatting entirely.
+    }
+  }
+}
+```
+
+To completely switch to another tool and prevent Ruff from modifying your code at all, you must explicitly set `source.organizeImports.ruff` to false in the `code_actions_on_format` section, in addition to changing the formatter.
+
+To prevent any formatting actions when you save, you can disable format-on-save for Python files in your `settings.json`:
+
+```json [settings]
+{
+  "languages": {
+    "Python": {
+      "format_on_save": "off"
     }
   }
 }