From d4413383580ea6a6c31ce4bde5ce8a96f0bee653 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ho=C3=ABl=20Bagard?=
 <34478245+hoel-bagard@users.noreply.github.com>
Date: Tue, 5 Mar 2024 12:08:30 +0900
Subject: [PATCH] Improve documentation of the preview mode (#10168)

## Summary

This PR was prompted by the discussion in #10153.
It adds CLI tab examples next to the `pyproject.toml` and `ruff.toml`
examples. It should be helpful for users wanting to try out the preview
mode without modifying or creating a `.toml` file.
It also adds a paragraph to try to make the effect of the preview mode
less confusing.
---
 docs/preview.md | 49 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/docs/preview.md b/docs/preview.md
index 2321500f55..bae159690a 100644
--- a/docs/preview.md
+++ b/docs/preview.md
@@ -3,8 +3,9 @@
 Ruff includes an opt-in preview mode to provide an opportunity for community feedback and increase confidence that
 changes are a net-benefit before enabling them for everyone.
 
-Preview mode enables a collection of newer lint rules, fixes, and formatter style changes that are
-considered experimental or unstable,.
+Preview mode enables a collection of unstable features such as new lint rules and fixes, formatter style changes, interface updates, and more. Warnings about deprecated features may turn into errors when using preview mode.
+
+Enabling preview mode does not on its own enable all preview rules. See the [rules section](#using-rules-that-are-in-preview) for details on selecting preview rules.
 
 ## Enabling preview mode
 
@@ -27,6 +28,13 @@ Preview mode can be configured separately for linting and formatting (requires R
     preview = true
     ```
 
+=== "CLI"
+
+    ```console
+    ruff check --preview
+    ```
+
+
 To enable preview style formatting without enabling any preview lint rules:
 
 === "pyproject.toml"
@@ -43,11 +51,16 @@ To enable preview style formatting without enabling any preview lint rules:
     preview = true
     ```
 
+=== "CLI"
+
+    ```console
+    ruff format --preview
+    ```
+
 ## Using rules that are in preview
 
 If a rule is marked as preview, it can only be selected if preview mode is enabled. For example, consider a
-hypothetical rule, `HYP001`. If `HYP001` were in preview, it would _not_ be enabled by adding following to your
-config file:
+hypothetical rule, `HYP001`. If `HYP001` were in preview, it would _not_ be enabled by adding it to the selected rule set.
 
 === "pyproject.toml"
 
@@ -63,6 +76,13 @@ config file:
     extend-select = ["HYP001"]
     ```
 
+=== "CLI"
+
+    ```console
+    ruff check --extend-select HYP001
+    ```
+
+
 It also would _not_ be enabled by selecting the `HYP` category, like so:
 
 === "pyproject.toml"
@@ -79,6 +99,13 @@ It also would _not_ be enabled by selecting the `HYP` category, like so:
     extend-select = ["HYP"]
     ```
 
+=== "CLI"
+
+    ```console
+    ruff check --extend-select HYP
+    ```
+
+
 Similarly, it would _not_ be enabled via the `ALL` selector:
 
 === "pyproject.toml"
@@ -95,7 +122,13 @@ Similarly, it would _not_ be enabled via the `ALL` selector:
     select = ["ALL"]
     ```
 
-However, it would be enabled in any of the above cases if you enabled preview in your configuration file:
+=== "CLI"
+
+    ```console
+    ruff check --select ALL
+    ```
+
+However, it _would_ be enabled in any of the above cases if you enabled preview mode:
 
 === "pyproject.toml"
 
@@ -113,7 +146,11 @@ However, it would be enabled in any of the above cases if you enabled preview in
     preview = true
     ```
 
-Or, if you provided the `--preview` CLI flag.
+=== "CLI"
+
+    ```console
+    ruff check --extend-select HYP --preview
+    ```
 
 To see which rules are currently in preview, visit the [rules reference](rules.md).