Add documentation for fixes (#7901)

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

Uses the draft of the "Automatic fixes" section from
#7732 and adds documentation for
unsafe fixes, applicability levels, and
#7841

I enabled admonitions because they're nice. We should use them more.

.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

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)

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: