From 81275d12e99753cf40495cccf8dad99d10b04250 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Wed, 11 Oct 2023 11:41:17 -0500
Subject: [PATCH] Add documentation for fixes (#7901)

Adds documentation for using `ruff check . --fix`

Uses the draft of the "Automatic fixes" section from
https://github.com/astral-sh/ruff/pull/7732 and adds documentation for
unsafe fixes, applicability levels, and
https://github.com/astral-sh/ruff/pull/7841

I enabled admonitions because they're nice. We should use them more.
---
 .pre-commit-config.yaml |  1 +
 docs/configuration.md   | 64 +++++++++++++++++++++++++++++++++++++++++
 mkdocs.template.yml     |  2 ++
 3 files changed, 67 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5da5eb2037..3008412e55 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -23,6 +23,7 @@ repos:
       - id: mdformat
         additional_dependencies:
           - mdformat-mkdocs
+          - mdformat-admon
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.33.0
diff --git a/docs/configuration.md b/docs/configuration.md
index 3ea4340aa3..9a6ea2d0b4 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -375,6 +375,70 @@ Running `ruff check --select F401` would result in Ruff enforcing `F401`, and no
 Running `ruff check --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules,
 with the exception of `F401`.
 
+## Fixes
+
+Ruff supports automatic fixes for a variety of lint errors. For example, Ruff can remove unused
+imports, reformat docstrings, rewrite type annotations to use newer Python syntax, and more.
+
+To enable fixes, pass the `--fix` flag to `ruff check`:
+
+```shell
+ruff check . --fix
+```
+
+By default, Ruff will fix all violations for which safe fixes are available; to determine
+whether a rule supports fixing, see [_Rules_](rules.md).
+
+### Fix safety
+
+Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code will be retained when applying safe fixes, but the meaning could be changed when applying unsafe fixes.
+
+Ruff only enables safe fixes by default. Unsafe fixes can be enabled by settings [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file or passing the `--unsafe-fixes` flag to `ruff check`:
+
+```shell
+# Show unsafe fixes
+ruff check . --unsafe-fixes
+
+# Apply unsafe fixes
+ruff check . --fix --unsafe-fixes 
+```
+
+The safety of fixes can be adjusted per rule using the [`extend-safe-fixes`](settings.md#extend-safe-fixes) and [`extend-unsafe-fixes`](settings.md#extend-unsafe-fixes) settings.
+
+For example, the following configuration would promote unsafe fixes for `F601` to safe fixes and demote safe fixes for `UP034` to unsafe fixes:
+
+```toml
+[tool.ruff.lint]
+extend-safe-fixes = ["F601"]
+extend-unsafe-fixes = ["UP034"]
+```
+
+You may use prefixes to select rules as well, e.g., `F` can be used to promote fixes for all rules in Pyflakes to safe.
+
+!!! note
+    All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field.
+
+### Disabling fixes
+
+To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and [`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) and [`extend-unfixable`](settings.md#extend-unfixable)
+variants.
+
+For example, the following configuration would enable fixes for all rules except
+[`unused-imports`](rules/unused-import.md) (`F401`):
+
+```toml
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = ["F401"]
+```
+
+Conversely, the following configuration would only enable fixes for `F401`:
+
+```toml
+[tool.ruff.lint]
+fixable = ["F401"]
+```
+
 ## Error suppression
 
 To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](settings.md#ignore)
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 171578868d..7eeed400e8 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -37,6 +37,8 @@ site_author: charliermarsh
 site_url: https://docs.astral.sh/ruff/
 site_dir: site/ruff
 markdown_extensions:
+  - admonition
+  - pymdownx.details
   - toc:
       permalink: "#"
   - pymdownx.snippets: