docs: Update the formatting section for Python (#48904)

Xin Zhao and Kunall Banerjee created 2 months ago

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 <[e-mail]>

Change summary

docs/src/languages/python.md | 37 +++++++++++++++++++++++++++++++------
1 file changed, 31 insertions(+), 6 deletions(-)

Detailed changes

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"
     }
   }
 }