Add preview documentation section (#7281)

Adds a basic documentation section for preview mode based on the FAQ
entry and versioning RFC.

docs/faq.md

@@ -384,42 +384,7 @@ alone.
 
 ## What is preview?
 
-Preview enables a collection of newer rules and fixes that are considered experimental or unstable.
+Preview enables a collection of newer rules and fixes that are considered experimental or unstable. See the [preview documentation](https://beta.ruff.rs/docs/preview/) for more details; or, to see which rules are currently in preview, visit the [rules reference](https://beta.ruff.rs/docs/rules/).
-
-If a rule is marked as preview, it can only be enabled if the `--preview` flag is toggled. For example, consider a
-hypothetical rule, `HYP001`. If `HYP001` were in preview, it would _not_ be enabled by adding following to your
-`pyproject.toml`:
-
-```toml
-[tool.ruff]
-extend-select = ["HYP001"]
-```
-
-It also would _not_ be enabled by selecting the `HYP` category, like so:
-
-```toml
-[tool.ruff]
-extend-select = ["HYP"]
-```
-
-Similarly, it would _not_ be enabled via the `ALL` selector:
-
-```toml
-[tool.ruff]
-select = ["ALL"]
-```
-
-However, it would be enabled in any of the above cases if you you enabled `preview`:
-
-```toml
-[tool.ruff]
-extend-select = ["HYP"]
-preview = true
-```
-
-Preview can also be enabled via the CLI with the `--preview` flag.
-
-To see which rules are currently in preview, visit the [rules reference](https://beta.ruff.rs/docs/rules/).
 
 ## How can I tell what settings Ruff is using to check my code?
 

docs/preview.md

@@ -0,0 +1,48 @@
+# Preview
+
+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 rules and fixes that are considered experimental or unstable.
+
+## Enabling preview mode
+
+Preview mode can be enabled with the `--preview` flag on the CLI or by setting `preview = true` in your Ruff
+configuration file (e.g. `pyproject.toml`).
+
+## 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
+`pyproject.toml`:
+
+```toml
+[tool.ruff]
+extend-select = ["HYP001"]
+```
+
+It also would _not_ be enabled by selecting the `HYP` category, like so:
+
+```toml
+[tool.ruff]
+extend-select = ["HYP"]
+```
+
+Similarly, it would _not_ be enabled via the `ALL` selector:
+
+```toml
+[tool.ruff]
+select = ["ALL"]
+```
+
+However, it would be enabled in any of the above cases if you you enabled preview in your configuration file:
+
+```toml
+[tool.ruff]
+extend-select = ["HYP"]
+preview = true
+```
+
+Or, if you provided the `--preview` CLI flag.
+
+To see which rules are currently in preview, visit the [rules reference](https://beta.ruff.rs/docs/rules/).

scripts/generate_mkdocs.py

@@ -25,6 +25,7 @@ SECTIONS: list[Section] = [
     Section("Installation", "installation.md", generated=False),
     Section("Usage", "usage.md", generated=False),
     Section("Configuration", "configuration.md", generated=False),
+    Section("Preview", "preview.md", generated=False),
     Section("Rules", "rules.md", generated=True),
     Section("Settings", "settings.md", generated=True),
     Section("Editor Integrations", "editor-integrations.md", generated=False),