diff --git a/docs/faq.md b/docs/faq.md index 84aab8057c..6002a2fc45 100644 --- a/docs/faq.md +++ b/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. - -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/). +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/). ## How can I tell what settings Ruff is using to check my code? diff --git a/docs/preview.md b/docs/preview.md new file mode 100644 index 0000000000..0d672950e3 --- /dev/null +++ b/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/). diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index f6954b153a..60ef1af94f 100644 --- a/scripts/generate_mkdocs.py +++ b/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),