From a1a536b2c57ae1a7cc9e84b60db0e8216a34fc9d Mon Sep 17 00:00:00 2001
From: Muspi Merol <me@promplate.dev>
Date: Tue, 25 Feb 2025 18:12:55 +0800
Subject: [PATCH] Normalize inconsistent markdown headings in docstrings
 (#16364)

I am working on a project that uses ruff linters' docs to generate a
fine-tuning dataset for LLMs.

To achieve this, I first ran the command `ruff rule --all
--output-format json` to retrieve all the rules. Then, I parsed the
explanation field to get these 3 consistent sections:

- `Why is this bad?`
- `What it does`
- `Example`

However, during the initial processing, I noticed that the markdown
headings are not that consistent. For instance:

- In most cases, `Use instead` appears as a normal paragraph within the
`Example` section, but in the file
`crates/ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs` it is
a level-2 heading
- The heading "What it does**?**" is used in some places, while others
consistently use "What it does"
- There are 831 `Example` headings and 65 `Examples`. But all of them
only have one example case

This PR normalized these across all rules.

## Test Plan

CI are passed.
---
 .../ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs   | 2 +-
 .../rules/flake8_bugbear/rules/reuse_of_groupby_generator.rs    | 2 +-
 .../rules/unnecessary_call_around_sorted.rs                     | 2 +-
 .../flake8_comprehensions/rules/unnecessary_collection_call.rs  | 2 +-
 .../flake8_comprehensions/rules/unnecessary_comprehension.rs    | 2 +-
 .../rules/unnecessary_comprehension_in_call.rs                  | 2 +-
 .../rules/unnecessary_dict_comprehension_for_iterable.rs        | 2 +-
 .../rules/unnecessary_double_cast_or_process.rs                 | 2 +-
 .../flake8_comprehensions/rules/unnecessary_generator_dict.rs   | 2 +-
 .../flake8_comprehensions/rules/unnecessary_generator_list.rs   | 2 +-
 .../flake8_comprehensions/rules/unnecessary_generator_set.rs    | 2 +-
 .../rules/flake8_comprehensions/rules/unnecessary_list_call.rs  | 2 +-
 .../rules/unnecessary_list_comprehension_dict.rs                | 2 +-
 .../rules/unnecessary_list_comprehension_set.rs                 | 2 +-
 .../flake8_comprehensions/rules/unnecessary_literal_dict.rs     | 2 +-
 .../flake8_comprehensions/rules/unnecessary_literal_set.rs      | 2 +-
 .../rules/unnecessary_literal_within_dict_call.rs               | 2 +-
 .../rules/unnecessary_literal_within_list_call.rs               | 2 +-
 .../rules/unnecessary_literal_within_tuple_call.rs              | 2 +-
 .../src/rules/flake8_comprehensions/rules/unnecessary_map.rs    | 2 +-
 .../rules/unnecessary_subscript_reversal.rs                     | 2 +-
 .../flake8_django/rules/unordered_body_content_in_model.rs      | 2 +-
 .../ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs   | 2 +-
 .../flake8_use_pathlib/rules/invalid_pathlib_with_suffix.rs     | 2 +-
 .../src/rules/flake8_use_pathlib/rules/os_path_getatime.rs      | 2 +-
 .../src/rules/flake8_use_pathlib/rules/os_path_getctime.rs      | 2 +-
 .../src/rules/flake8_use_pathlib/rules/os_path_getmtime.rs      | 2 +-
 .../src/rules/flake8_use_pathlib/rules/os_path_getsize.rs       | 2 +-
 crates/ruff_linter/src/rules/numpy/rules/deprecated_function.rs | 2 +-
 .../ruff_linter/src/rules/numpy/rules/deprecated_type_alias.rs  | 2 +-
 crates/ruff_linter/src/rules/numpy/rules/legacy_random.rs       | 2 +-
 .../ruff_linter/src/rules/numpy/rules/numpy_2_0_deprecation.rs  | 2 +-
 .../src/rules/pyupgrade/rules/unnecessary_class_parentheses.rs  | 2 +-
 .../src/rules/pyupgrade/rules/unnecessary_default_type_args.rs  | 2 +-
 .../src/rules/refurb/rules/unnecessary_from_float.rs            | 2 +-
 crates/ruff_linter/src/rules/ruff/rules/assignment_in_assert.rs | 2 +-
 .../ruff_linter/src/rules/ruff/rules/default_factory_kwarg.rs   | 2 +-
 .../src/rules/ruff/rules/function_call_in_dataclass_default.rs  | 2 +-
 .../rules/ruff/rules/invalid_formatter_suppression_comment.rs   | 2 +-
 .../src/rules/ruff/rules/mutable_dataclass_default.rs           | 2 +-
 .../ruff_linter/src/rules/ruff/rules/unnecessary_key_check.rs   | 2 +-
 .../rules/ruff/rules/unnecessary_literal_within_deque_call.rs   | 2 +-
 crates/ruff_linter/src/rules/ruff/rules/unused_async.rs         | 2 +-
 43 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/crates/ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs b/crates/ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs
index b3c9266b60..b1e033a38b 100644
--- a/crates/ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs
+++ b/crates/ruff_linter/src/rules/flake8_bandit/rules/django_extra.rs
@@ -22,7 +22,7 @@ use crate::checkers::ast::Checker;
 /// User.objects.all().extra(select={"test": "%secure" % "nos"})
 /// ```
 ///
-/// ## Use instead:
+/// Use instead:
 /// ```python
 /// from django.contrib.auth.models import User
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_bugbear/rules/reuse_of_groupby_generator.rs b/crates/ruff_linter/src/rules/flake8_bugbear/rules/reuse_of_groupby_generator.rs
index 18487040d1..0e70f8aa22 100644
--- a/crates/ruff_linter/src/rules/flake8_bugbear/rules/reuse_of_groupby_generator.rs
+++ b/crates/ruff_linter/src/rules/flake8_bugbear/rules/reuse_of_groupby_generator.rs
@@ -15,7 +15,7 @@ use crate::checkers::ast::Checker;
 /// Using the generator more than once will do nothing on the second usage.
 /// If that data is needed later, it should be stored as a list.
 ///
-/// ## Examples:
+/// ## Example:
 /// ```python
 /// import itertools
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_call_around_sorted.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_call_around_sorted.rs
index 70794a9304..13dc492086 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_call_around_sorted.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_call_around_sorted.rs
@@ -21,7 +21,7 @@ use crate::rules::flake8_comprehensions::fixes;
 ///
 /// In both cases, it's clearer and more efficient to avoid the redundant call.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// reversed(sorted(iterable))
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_collection_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_collection_call.rs
index dc16511336..510d73bddb 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_collection_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_collection_call.rs
@@ -17,7 +17,7 @@ use crate::rules::flake8_comprehensions::settings::Settings;
 /// literal (`{}`). The former is slower because the name `dict` must be
 /// looked up in the global scope in case it has been rebound.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// dict()
 /// dict(a=1, b=2)
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs
index a9d411feee..922e000234 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs
@@ -15,7 +15,7 @@ use crate::rules::flake8_comprehensions::fixes;
 /// It's unnecessary to use a dict/list/set comprehension to build a data structure if the
 /// elements are unchanged. Wrap the iterable with `dict()`, `list()`, or `set()` instead.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// {a: b for a, b in iterable}
 /// [x for x in iterable]
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension_in_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension_in_call.rs
index aa3826dd04..cfa611e7de 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension_in_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension_in_call.rs
@@ -41,7 +41,7 @@ use crate::rules::flake8_comprehensions::fixes;
 /// short-circuiting it may not improve performance. (It may even slightly regress performance,
 /// though the difference will usually be small.)
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// any([x.id for x in bar])
 /// all([x.id for x in bar])
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_dict_comprehension_for_iterable.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_dict_comprehension_for_iterable.rs
index e30843c1b3..7f56ecfaeb 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_dict_comprehension_for_iterable.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_dict_comprehension_for_iterable.rs
@@ -19,7 +19,7 @@ use crate::checkers::ast::Checker;
 /// Prefer `dict.fromkeys(iterable)` over `{value: None for value in iterable}`,
 /// as `dict.fromkeys` is more readable and efficient.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// {a: None for a in iterable}
 /// {a: 1 for a in iterable}
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_double_cast_or_process.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_double_cast_or_process.rs
index 4ce5712802..48a16d57e3 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_double_cast_or_process.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_double_cast_or_process.rs
@@ -17,7 +17,7 @@ use crate::rules::flake8_comprehensions::fixes;
 /// the listed functions within an additional `list()`, `set()`, `sorted()`, or
 /// `tuple()` call. Doing so is redundant and can be confusing for readers.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// list(tuple(iterable))
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_dict.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_dict.rs
index 6b03d813b8..ea7f036eeb 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_dict.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_dict.rs
@@ -18,7 +18,7 @@ use super::helpers;
 /// there are equivalent comprehensions for these types. Using a
 /// comprehension is clearer and more idiomatic.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// dict((x, f(x)) for x in foo)
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_list.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_list.rs
index c2345fdcce..e2739c5ab7 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_list.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_list.rs
@@ -24,7 +24,7 @@ use super::helpers;
 /// `list(x for x in foo)`, it's better to use `list(foo)` directly, since it's
 /// even more direct.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// list(f(x) for x in foo)
 /// list(x for x in foo)
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_set.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_set.rs
index e04c67cb94..4582a274ac 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_set.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_set.rs
@@ -25,7 +25,7 @@ use super::helpers;
 /// `set(x for x in foo)`, it's better to use `set(foo)` directly, since it's
 /// even more direct.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// set(f(x) for x in foo)
 /// set(x for x in foo)
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_call.rs
index f5d3bf84b5..851c4be16a 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_call.rs
@@ -16,7 +16,7 @@ use super::helpers;
 /// ## Why is this bad?
 /// It is redundant to use a `list()` call around a list comprehension.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// list([f(x) for x in foo])
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_dict.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_dict.rs
index 183a065d75..4bad3a17ca 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_dict.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_dict.rs
@@ -16,7 +16,7 @@ use super::helpers;
 /// It's unnecessary to use a list comprehension inside a call to `dict()`,
 /// since there is an equivalent comprehension for this type.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// dict([(x, f(x)) for x in foo])
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_set.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_set.rs
index 4a91ff7c5e..be2c563295 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_set.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_set.rs
@@ -17,7 +17,7 @@ use super::helpers;
 /// It's unnecessary to use a list comprehension inside a call to `set()`,
 /// since there is an equivalent comprehension for this type.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// set([f(x) for x in foo])
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_dict.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_dict.rs
index c47e445766..3ccfccda35 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_dict.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_dict.rs
@@ -16,7 +16,7 @@ use super::helpers;
 /// It's unnecessary to use a list or tuple literal within a call to `dict()`.
 /// It can be rewritten as a dict literal (`{}`).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// dict([(1, 2), (3, 4)])
 /// dict(((1, 2), (3, 4)))
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_set.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_set.rs
index 85fdfcee9b..31f33bf520 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_set.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_set.rs
@@ -16,7 +16,7 @@ use super::helpers;
 /// It's unnecessary to use a list or tuple literal within a call to `set()`.
 /// Instead, the expression can be rewritten as a set literal.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// set([1, 2])
 /// set((1, 2))
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_dict_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_dict_call.rs
index 37e377f9bc..7b24cb8d9f 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_dict_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_dict_call.rs
@@ -19,7 +19,7 @@ use super::helpers;
 /// call, since the literal or comprehension syntax already returns a
 /// dictionary.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// dict({})
 /// dict({"a": 1})
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_list_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_list_call.rs
index 97e52666d7..72bad6b12f 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_list_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_list_call.rs
@@ -19,7 +19,7 @@ use super::helpers;
 /// removed. Otherwise, if a tuple literal is passed in, then it should be
 /// rewritten as a list literal.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// list([1, 2])
 /// list((1, 2))
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_tuple_call.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_tuple_call.rs
index d39d3d4733..50a44a31f5 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_tuple_call.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_tuple_call.rs
@@ -27,7 +27,7 @@ use super::helpers;
 /// calls. If a list comprehension is found, it should be rewritten as a
 /// generator expression.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// tuple([1, 2])
 /// tuple((1, 2))
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_map.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_map.rs
index 89da8a12d8..394c045d48 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_map.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_map.rs
@@ -30,7 +30,7 @@ use crate::rules::flake8_comprehensions::fixes;
 /// - Instead of `dict(map(lambda v: (v, v ** 2), values))`, use
 ///   `{v: v ** 2 for v in values}`.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// map(lambda x: x + 1, iterable)
 /// ```
diff --git a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_subscript_reversal.rs b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_subscript_reversal.rs
index e7bae7b700..77a1d98070 100644
--- a/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_subscript_reversal.rs
+++ b/crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_subscript_reversal.rs
@@ -13,7 +13,7 @@ use crate::checkers::ast::Checker;
 /// into `reversed()`, `set()` or `sorted()` functions as they will change
 /// the order of the elements again.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// sorted(iterable[::-1])
 /// set(iterable[::-1])
diff --git a/crates/ruff_linter/src/rules/flake8_django/rules/unordered_body_content_in_model.rs b/crates/ruff_linter/src/rules/flake8_django/rules/unordered_body_content_in_model.rs
index 71a2a5a2a5..fa4c994c73 100644
--- a/crates/ruff_linter/src/rules/flake8_django/rules/unordered_body_content_in_model.rs
+++ b/crates/ruff_linter/src/rules/flake8_django/rules/unordered_body_content_in_model.rs
@@ -27,7 +27,7 @@ use super::helpers;
 /// 6. `def get_absolute_url()`
 /// 7. Any custom methods
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// from django.db import models
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs
index 3f0577928f..2e8035af07 100644
--- a/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs
+++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs
@@ -145,7 +145,7 @@ impl AlwaysFixableViolation for AssignmentDefaultInStub {
     }
 }
 
-/// ## What it does?
+/// ## What it does
 /// Checks for unannotated assignments in stub (`.pyi`) files.
 ///
 /// ## Why is this bad?
diff --git a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/invalid_pathlib_with_suffix.rs b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/invalid_pathlib_with_suffix.rs
index 142650ed6a..d927d150f2 100644
--- a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/invalid_pathlib_with_suffix.rs
+++ b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/invalid_pathlib_with_suffix.rs
@@ -16,7 +16,7 @@ use ruff_text_size::Ranged;
 /// if the given suffix is not prefixed with a dot
 /// or it is a single dot `"."`.
 ///
-/// ## Examples
+/// ## Example
 ///
 /// ```python
 /// path.with_suffix("py")
diff --git a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getatime.rs b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getatime.rs
index 15da2eb416..d4645dcbce 100644
--- a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getatime.rs
+++ b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getatime.rs
@@ -12,7 +12,7 @@ use ruff_macros::{derive_message_formats, ViolationMetadata};
 /// improve readability over the `os.path` module's counterparts (e.g.,
 /// `os.path.getatime()`).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import os
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getctime.rs b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getctime.rs
index 0eae426b35..8c645f2994 100644
--- a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getctime.rs
+++ b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getctime.rs
@@ -12,7 +12,7 @@ use ruff_macros::{derive_message_formats, ViolationMetadata};
 /// improve readability over the `os.path` module's counterparts (e.g.,
 /// `os.path.getctime()`).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import os
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getmtime.rs b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getmtime.rs
index dbc1f1d500..9237a307b0 100644
--- a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getmtime.rs
+++ b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getmtime.rs
@@ -12,7 +12,7 @@ use ruff_macros::{derive_message_formats, ViolationMetadata};
 /// improve readability over the `os.path` module's counterparts (e.g.,
 /// `os.path.getmtime()`).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import os
 ///
diff --git a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getsize.rs b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getsize.rs
index 94b5b793ee..b642783023 100644
--- a/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getsize.rs
+++ b/crates/ruff_linter/src/rules/flake8_use_pathlib/rules/os_path_getsize.rs
@@ -12,7 +12,7 @@ use ruff_macros::{derive_message_formats, ViolationMetadata};
 /// improve readability over the `os.path` module's counterparts (e.g.,
 /// `os.path.getsize()`).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import os
 ///
diff --git a/crates/ruff_linter/src/rules/numpy/rules/deprecated_function.rs b/crates/ruff_linter/src/rules/numpy/rules/deprecated_function.rs
index 06a61d9373..caf6afc133 100644
--- a/crates/ruff_linter/src/rules/numpy/rules/deprecated_function.rs
+++ b/crates/ruff_linter/src/rules/numpy/rules/deprecated_function.rs
@@ -17,7 +17,7 @@ use crate::importer::ImportRequest;
 ///
 /// Prefer newer APIs over deprecated ones.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import numpy as np
 ///
diff --git a/crates/ruff_linter/src/rules/numpy/rules/deprecated_type_alias.rs b/crates/ruff_linter/src/rules/numpy/rules/deprecated_type_alias.rs
index 675a669268..3e5ee760a0 100644
--- a/crates/ruff_linter/src/rules/numpy/rules/deprecated_type_alias.rs
+++ b/crates/ruff_linter/src/rules/numpy/rules/deprecated_type_alias.rs
@@ -19,7 +19,7 @@ use crate::checkers::ast::Checker;
 /// Note, however, that `np.bool` and `np.long` were reintroduced in 2.0 with
 /// different semantics, and are thus omitted from this rule.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import numpy as np
 ///
diff --git a/crates/ruff_linter/src/rules/numpy/rules/legacy_random.rs b/crates/ruff_linter/src/rules/numpy/rules/legacy_random.rs
index 4174d8e6e3..9be089f24a 100644
--- a/crates/ruff_linter/src/rules/numpy/rules/legacy_random.rs
+++ b/crates/ruff_linter/src/rules/numpy/rules/legacy_random.rs
@@ -28,7 +28,7 @@ use crate::checkers::ast::Checker;
 /// See the documentation on [Random Sampling] and [NEP 19] for further
 /// details.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import numpy as np
 ///
diff --git a/crates/ruff_linter/src/rules/numpy/rules/numpy_2_0_deprecation.rs b/crates/ruff_linter/src/rules/numpy/rules/numpy_2_0_deprecation.rs
index e5f7be5479..730a6a5137 100644
--- a/crates/ruff_linter/src/rules/numpy/rules/numpy_2_0_deprecation.rs
+++ b/crates/ruff_linter/src/rules/numpy/rules/numpy_2_0_deprecation.rs
@@ -31,7 +31,7 @@ use crate::importer::ImportRequest;
 /// This rule flags all uses of removed members, along with automatic fixes for
 /// any backwards-compatible replacements.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// import numpy as np
 ///
diff --git a/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_class_parentheses.rs b/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_class_parentheses.rs
index d671e0c337..832272d5f5 100644
--- a/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_class_parentheses.rs
+++ b/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_class_parentheses.rs
@@ -13,7 +13,7 @@ use crate::checkers::ast::Checker;
 /// If a class definition doesn't have any bases, the parentheses are
 /// unnecessary.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// class Foo():
 ///     ...
diff --git a/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_default_type_args.rs b/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_default_type_args.rs
index 4a994f7b6b..b95125b515 100644
--- a/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_default_type_args.rs
+++ b/crates/ruff_linter/src/rules/pyupgrade/rules/unnecessary_default_type_args.rs
@@ -20,7 +20,7 @@ use crate::checkers::ast::Checker;
 /// Omitting type arguments that match the default values can make the code
 /// more concise and easier to read.
 ///
-/// ## Examples
+/// ## Example
 ///
 /// ```python
 /// from collections.abc import Generator, AsyncGenerator
diff --git a/crates/ruff_linter/src/rules/refurb/rules/unnecessary_from_float.rs b/crates/ruff_linter/src/rules/refurb/rules/unnecessary_from_float.rs
index 60cf8233b8..0d07fae3ce 100644
--- a/crates/ruff_linter/src/rules/refurb/rules/unnecessary_from_float.rs
+++ b/crates/ruff_linter/src/rules/refurb/rules/unnecessary_from_float.rs
@@ -15,7 +15,7 @@ use crate::checkers::ast::Checker;
 /// the use of `from_float` and `from_decimal` methods is unnecessary, and
 /// should be avoided in favor of the more concise constructor syntax.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// Decimal.from_float(4.2)
 /// Decimal.from_float(float("inf"))
diff --git a/crates/ruff_linter/src/rules/ruff/rules/assignment_in_assert.rs b/crates/ruff_linter/src/rules/ruff/rules/assignment_in_assert.rs
index 792f71dd3e..69d098457a 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/assignment_in_assert.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/assignment_in_assert.rs
@@ -19,7 +19,7 @@ use crate::checkers::ast::Checker;
 /// which may result in unexpected behavior (e.g., undefined variable
 /// accesses).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// assert (x := 0) == 0
 /// print(x)
diff --git a/crates/ruff_linter/src/rules/ruff/rules/default_factory_kwarg.rs b/crates/ruff_linter/src/rules/ruff/rules/default_factory_kwarg.rs
index 14613afe12..fc5cc0aaa6 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/default_factory_kwarg.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/default_factory_kwarg.rs
@@ -38,7 +38,7 @@ use crate::Locator;
 /// keyword to a positional argument will change the behavior of the code, even
 /// if the keyword argument was used erroneously.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// defaultdict(default_factory=int)
 /// defaultdict(default_factory=list)
diff --git a/crates/ruff_linter/src/rules/ruff/rules/function_call_in_dataclass_default.rs b/crates/ruff_linter/src/rules/ruff/rules/function_call_in_dataclass_default.rs
index 7a514d61fb..71e6331d65 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/function_call_in_dataclass_default.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/function_call_in_dataclass_default.rs
@@ -29,7 +29,7 @@ use crate::rules::ruff::rules::helpers::{
 /// Attributes whose default arguments are `NewType` calls
 /// where the original type is immutable are ignored.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// from dataclasses import dataclass
 ///
diff --git a/crates/ruff_linter/src/rules/ruff/rules/invalid_formatter_suppression_comment.rs b/crates/ruff_linter/src/rules/ruff/rules/invalid_formatter_suppression_comment.rs
index 887e05df05..b3fac6e6ca 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/invalid_formatter_suppression_comment.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/invalid_formatter_suppression_comment.rs
@@ -26,7 +26,7 @@ use super::suppression_comment_visitor::{
 /// Suppression comments that do not actually prevent formatting could cause unintended changes
 /// when the formatter is run.
 ///
-/// ## Examples
+/// ## Example
 /// In the following example, all suppression comments would cause
 /// a rule violation.
 ///
diff --git a/crates/ruff_linter/src/rules/ruff/rules/mutable_dataclass_default.rs b/crates/ruff_linter/src/rules/ruff/rules/mutable_dataclass_default.rs
index 9cec4913dd..341af13c67 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/mutable_dataclass_default.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/mutable_dataclass_default.rs
@@ -22,7 +22,7 @@ use crate::rules::ruff::rules::helpers::{dataclass_kind, is_class_var_annotation
 /// If the default value is intended to be mutable, it must be annotated with
 /// `typing.ClassVar`; otherwise, a `ValueError` will be raised.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// from dataclasses import dataclass
 ///
diff --git a/crates/ruff_linter/src/rules/ruff/rules/unnecessary_key_check.rs b/crates/ruff_linter/src/rules/ruff/rules/unnecessary_key_check.rs
index 6957d191d2..4a443fa199 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/unnecessary_key_check.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/unnecessary_key_check.rs
@@ -17,7 +17,7 @@ use crate::checkers::ast::Checker;
 /// without having to check if the dictionary contains the relevant key,
 /// returning `None` if the key is not present.
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// if "key" in dct and dct["key"]:
 ///     ...
diff --git a/crates/ruff_linter/src/rules/ruff/rules/unnecessary_literal_within_deque_call.rs b/crates/ruff_linter/src/rules/ruff/rules/unnecessary_literal_within_deque_call.rs
index b9b51cfec3..47b3f712ad 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/unnecessary_literal_within_deque_call.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/unnecessary_literal_within_deque_call.rs
@@ -10,7 +10,7 @@ use ruff_text_size::Ranged;
 /// ## Why is this bad?
 /// It's unnecessary to use an empty literal as a deque's iterable, since this is already the default behavior.
 ///
-/// ## Examples
+/// ## Example
 ///
 /// ```python
 /// from collections import deque
diff --git a/crates/ruff_linter/src/rules/ruff/rules/unused_async.rs b/crates/ruff_linter/src/rules/ruff/rules/unused_async.rs
index 6ef9495c60..e3fb4cb8d9 100644
--- a/crates/ruff_linter/src/rules/ruff/rules/unused_async.rs
+++ b/crates/ruff_linter/src/rules/ruff/rules/unused_async.rs
@@ -18,7 +18,7 @@ use crate::rules::fastapi::rules::is_fastapi_route;
 /// contexts where that function may be called. In some cases, labeling a function `async` is
 /// semantically meaningful (e.g. with the trio library).
 ///
-/// ## Examples
+/// ## Example
 /// ```python
 /// async def foo():
 ///     bar()