Adjust heading level in rule documentation (#2749)

README.md

@@ -3415,7 +3415,7 @@ alias (e.g., `import A as B`) to wrap such that every line contains
 exactly one member. For example, this formatting would be retained,
 rather than condensing to a single line:
 
-```py
+```python
 from .utils import (
     test_directory as test_directory,
     test_id as test_id

crates/ruff/src/rules/eradicate/rules.rs

@@ -10,14 +10,14 @@ use crate::source_code::Locator;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for commented-out Python code.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Commented-out code is dead code, and is often included inadvertently.
     /// It should be removed.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// # print('foo')
     /// ```

crates/ruff/src/rules/flake8_annotations/rules.rs

@@ -16,15 +16,15 @@ use crate::visibility;
 use crate::visibility::Visibility;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(x):
     ///     ...
@@ -48,15 +48,15 @@ impl Violation for MissingTypeFunctionArgument {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function `*args` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(*args):
     ///     ...
@@ -80,15 +80,15 @@ impl Violation for MissingTypeArgs {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function `**kwargs` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(**kwargs):
     ///     ...
@@ -112,10 +112,10 @@ impl Violation for MissingTypeKwargs {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that instance method `self` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
@@ -123,7 +123,7 @@ define_violation!(
     /// Note that many type checkers will infer the type of `self` automatically, so this
     /// annotation is not strictly necessary.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     def bar(self):
@@ -149,10 +149,10 @@ impl Violation for MissingTypeSelf {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that class method `cls` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
@@ -160,7 +160,7 @@ define_violation!(
     /// Note that many type checkers will infer the type of `cls` automatically, so this
     /// annotation is not strictly necessary.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @classmethod
@@ -188,15 +188,15 @@ impl Violation for MissingTypeCls {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that public functions and methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def add(a, b):
     ///     return a + b
@@ -220,15 +220,15 @@ impl Violation for MissingReturnTypePublicFunction {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that private functions and methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def _add(a, b):
     ///     return a + b
@@ -252,11 +252,11 @@ impl Violation for MissingReturnTypePrivateFunction {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
     /// return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
@@ -271,7 +271,7 @@ define_violation!(
     /// mypy-init-return = true
     /// ```
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     def __init__(self, x: int):
@@ -301,15 +301,15 @@ impl AlwaysAutofixableViolation for MissingReturnTypeSpecialMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that static methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @staticmethod
@@ -337,15 +337,15 @@ impl Violation for MissingReturnTypeStaticMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that class methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @classmethod
@@ -373,11 +373,11 @@ impl Violation for MissingReturnTypeClassMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that an expression is annotated with a more specific type than
     /// `Any`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// `Any` is a special type indicating an unconstrained type. When an
     /// expression is annotated with type `Any`, type checkers will allow all
     /// operations on it.
@@ -385,7 +385,7 @@ define_violation!(
     /// It's better to be explicit about the type of an expression, and to use
     /// `Any` as an "escape hatch" only when it is really needed.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(x: Any):
     ///     ...
@@ -397,7 +397,7 @@ define_violation!(
     ///     ...
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-any-type)
     /// * [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)
     /// * [Mypy: The Any type](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#the-any-type)

crates/ruff/src/rules/flake8_bandit/rules/hardcoded_sql_expression.rs

@@ -16,23 +16,23 @@ static SQL_REGEX: Lazy<Regex> = Lazy::new(|| {
 });
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for strings that resemble SQL statements involved in some form
     /// string building operation.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// SQL injection is a common attack vector for web applications. Directly
     /// interpolating user input into SQL statements should always be avoided.
     /// Instead, favor parameterized queries, in which the SQL statement is
     /// provided separately from its parameters, as supported by `psycopg3`
     /// and other database drivers and ORMs.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// query = "DELETE FROM foo WHERE id = '%s'" % identifier
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [B608: Test for SQL injection](https://bandit.readthedocs.io/en/latest/plugins/b608_hardcoded_sql_expressions.html)
     /// * [psycopg3: Server-side binding](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html#server-side-binding)
     pub struct HardcodedSQLExpression {

crates/ruff/src/rules/flake8_bugbear/rules/assert_raises_exception.rs

@@ -7,17 +7,17 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for `self.assertRaises(Exception)`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// `assertRaises(Exception)` can lead to your test passing even if the
     /// code being tested is never executed due to a typo.
     ///
     /// Either assert for a more specific exception (builtin or custom), use
     /// `assertRaisesRegex` or the context manager form of `assertRaises`.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// self.assertRaises(Exception, foo)
     /// ```

crates/ruff/src/rules/flake8_import_conventions/rules.rs

@@ -7,11 +7,11 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for imports that are typically imported using a common convention,
     /// like `import pandas as pd`, and enforces that convention.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use a common convention for imports to make your code
     /// more readable and idiomatic.
     ///
@@ -19,7 +19,7 @@ define_violation!(
     /// convention for importing the `pandas` library, and users typically expect
     /// Pandas to be aliased as `pd`.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import pandas
     /// ```

crates/ruff/src/rules/flake8_no_pep420/rules.rs

@@ -8,10 +8,10 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for packages that are missing an `__init__.py` file.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Python packages are directories that contain a file named `__init__.py`.
     /// The existence of this file indicates that the directory is a Python
     /// package, and so it can be imported the same way a module can be

crates/ruff/src/rules/flake8_pyi/rules.rs

@@ -26,15 +26,15 @@ impl fmt::Display for VarKind {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that type `TypeVar`, `ParamSpec`, and `TypeVarTuple` definitions in
     /// stubs are prefixed with `_`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// By prefixing type parameters with `_`, we can avoid accidentally exposing
     /// names internal to the stub.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// from typing import TypeVar
     ///

crates/ruff/src/rules/flake8_quotes/rules.rs

@@ -12,16 +12,16 @@ use crate::source_code::Locator;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for inline strings that use single quotes or double quotes,
     /// depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for inline
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = 'bar'
     /// ```
@@ -54,16 +54,16 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for multiline strings that use single quotes or double quotes,
     /// depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for multiline
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = '''
     /// bar
@@ -100,15 +100,15 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for docstring
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// '''
     /// bar
@@ -145,15 +145,15 @@ impl AlwaysAutofixableViolation for BadQuotesDocstring {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for strings that include escaped quotes, and suggests changing
     /// the quote style to avoid the need to escape them.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// It's preferable to avoid escaped quotes in strings. By changing the
     /// outer quote style, you can avoid escaping inner quotes.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = 'bar\'s'
     /// ```

crates/ruff/src/rules/isort/rules/add_required_imports.rs

@@ -15,16 +15,16 @@ use crate::source_code::{Locator, Stylist};
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Adds any required imports, as specified by the user, to the top of the file.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// In some projects, certain imports are required to be present in all files. For
     /// example, some projects assume that `from __future__ import annotations` is enabled,
     /// and thus require that import to be present in all files. Omitting a "required" import
     /// (as specified by the user) can cause errors or unexpected behavior.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import typing
     /// ```

crates/ruff/src/rules/isort/rules/organize_imports.rs

@@ -19,14 +19,14 @@ use crate::source_code::{Indexer, Locator, Stylist};
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// De-duplicates, groups, and sorts imports based on the provided `isort` settings.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use a common convention for imports to make your code
     /// more readable and idiomatic.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import pandas
     /// import numpy as np

crates/ruff/src/rules/isort/settings.rs

@@ -47,7 +47,7 @@ pub struct Options {
     /// exactly one member. For example, this formatting would be retained,
     /// rather than condensing to a single line:
     ///
-    /// ```py
+    /// ```python
     /// from .utils import (
     ///     test_directory as test_directory,
     ///     test_id as test_id

crates/ruff/src/rules/mccabe/rules.rs

@@ -7,7 +7,7 @@ use crate::source_code::Locator;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for functions with a high `McCabe` complexity.
     ///
     /// The `McCabe` complexity of a function is a measure of the complexity of the
@@ -15,10 +15,10 @@ define_violation!(
     /// number of decision points in the function. A decision point is a place in
     /// the code where the program has a choice of two or more paths to follow.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Functions with a high complexity are hard to understand and maintain.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(a, b, c):
     ///     if a:

crates/ruff/src/rules/pylint/rules/bad_string_format_type.rs

@@ -15,14 +15,14 @@ use crate::rules::pydocstyle::helpers::{leading_quote, trailing_quote};
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for mismatched argument types in "old-style" format strings.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// The format string is not checked at compile time, so it is easy to
     /// introduce bugs by mistyping the format string.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// print("%d" % "1")
     /// ```

crates/ruff/src/rules/pylint/rules/yield_in_init.rs

@@ -12,11 +12,11 @@ use crate::{
 };
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for `__init__` methods that are turned into generators by the
     /// inclusion of `yield` or `yield from` expressions.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// The `__init__` method is the constructor for a given Python class,
     /// responsible for initializing, rather than creating, new objects.
     ///
@@ -24,14 +24,14 @@ define_violation!(
     /// `yield from` expression in an `__init__`, the method will return a
     /// generator object when called at runtime, resulting in a runtime error.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class InitIsGenerator:
     ///     def __init__(self, i):
     ///         yield i
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [`py-init-method-is-generator`](https://codeql.github.com/codeql-query-help/python/py-init-method-is-generator/)
     pub struct YieldInInit;
 );

crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs

@@ -7,10 +7,10 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for code that raises `Exception` directly.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Handling such exceptions requires the use of `except Exception`, which
     /// captures _any_ raised exception, including failed assertions,
     /// division by zero, and more.
@@ -19,8 +19,8 @@ define_violation!(
     /// exception, so that you can avoid over-capturing exceptions that you
     /// don't intend to handle.
     ///
-    /// ### Example
-    /// ```py
+    /// ## Example
+    /// ```python
     /// def main_function():
     ///     if not cond:
     ///         raise Exception()
@@ -34,7 +34,7 @@ define_violation!(
     /// ```
     ///
     /// Use instead:
-    /// ```py
+    /// ```python
     /// def main_function():
     ///     if not cond:
     ///         raise CustomException()
@@ -47,6 +47,7 @@ define_violation!(
     ///         logger.error("Main function failed")
     ///     except Exception:
     ///         logger.error("Oops")
+    /// ```
     pub struct RaiseVanillaClass;
 );
 impl Violation for RaiseVanillaClass {

docs/rules/any-type.md

@@ -2,11 +2,11 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that an expression is annotated with a more specific type than
 `Any`.
 
-### Why is this bad?
+## Why is this bad?
 `Any` is a special type indicating an unconstrained type. When an
 expression is annotated with type `Any`, type checkers will allow all
 operations on it.
@@ -14,7 +14,7 @@ operations on it.
 It's better to be explicit about the type of an expression, and to use
 `Any` as an "escape hatch" only when it is really needed.
 
-### Example
+## Example
 ```python
 def foo(x: Any):
     ...
@@ -26,7 +26,7 @@ def foo(x: int):
     ...
 ```
 
-### References
+## References
 * [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-any-type)
 * [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)
 * [Mypy: The Any type](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#the-any-type)

docs/rules/assert-raises-exception.md

@@ -2,17 +2,17 @@
 
 Derived from the **flake8-bugbear** linter.
 
-### What it does
+## What it does
 Checks for `self.assertRaises(Exception)`.
 
-### Why is this bad?
+## Why is this bad?
 `assertRaises(Exception)` can lead to your test passing even if the
 code being tested is never executed due to a typo.
 
 Either assert for a more specific exception (builtin or custom), use
 `assertRaisesRegex` or the context manager form of `assertRaises`.
 
-### Example
+## Example
 ```python
 self.assertRaises(Exception, foo)
 ```

docs/rules/avoidable-escaped-quote.md

@@ -4,15 +4,15 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for strings that include escaped quotes, and suggests changing
 the quote style to avoid the need to escape them.
 
-### Why is this bad?
+## Why is this bad?
 It's preferable to avoid escaped quotes in strings. By changing the
 outer quote style, you can avoid escaping inner quotes.
 
-### Example
+## Example
 ```python
 foo = 'bar\'s'
 ```

docs/rules/bad-quotes-docstring.md

@@ -4,15 +4,15 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for docstring
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 '''
 bar

docs/rules/bad-quotes-inline-string.md

@@ -4,16 +4,16 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for inline strings that use single quotes or double quotes,
 depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for inline
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 foo = 'bar'
 ```

docs/rules/bad-quotes-multiline-string.md

@@ -4,16 +4,16 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for multiline strings that use single quotes or double quotes,
 depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for multiline
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 foo = '''
 bar

docs/rules/bad-string-format-type.md

@@ -2,14 +2,14 @@
 
 Derived from the **Pylint** linter.
 
-### What it does
+## What it does
 Checks for mismatched argument types in "old-style" format strings.
 
-### Why is this bad?
+## Why is this bad?
 The format string is not checked at compile time, so it is easy to
 introduce bugs by mistyping the format string.
 
-### Example
+## Example
 ```python
 print("%d" % "1")
 ```

docs/rules/commented-out-code.md

@@ -4,14 +4,14 @@ Derived from the **eradicate** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for commented-out Python code.
 
-### Why is this bad?
+## Why is this bad?
 Commented-out code is dead code, and is often included inadvertently.
 It should be removed.
 
-### Example
+## Example
 ```python
 # print('foo')
 ```

docs/rules/function-is-too-complex.md

@@ -2,7 +2,7 @@
 
 Derived from the **mccabe** linter.
 
-### What it does
+## What it does
 Checks for functions with a high `McCabe` complexity.
 
 The `McCabe` complexity of a function is a measure of the complexity of the
@@ -10,10 +10,10 @@ control flow graph of the function. It is calculated by adding one to the
 number of decision points in the function. A decision point is a place in
 the code where the program has a choice of two or more paths to follow.
 
-### Why is this bad?
+## Why is this bad?
 Functions with a high complexity are hard to understand and maintain.
 
-### Example
+## Example
 ```python
 def foo(a, b, c):
     if a:

docs/rules/hardcoded-sql-expression.md

@@ -2,22 +2,22 @@
 
 Derived from the **flake8-bandit** linter.
 
-### What it does
+## What it does
 Checks for strings that resemble SQL statements involved in some form
 string building operation.
 
-### Why is this bad?
+## Why is this bad?
 SQL injection is a common attack vector for web applications. Directly
 interpolating user input into SQL statements should always be avoided.
 Instead, favor parameterized queries, in which the SQL statement is
 provided separately from its parameters, as supported by `psycopg3`
 and other database drivers and ORMs.
 
-### Example
+## Example
 ```python
 query = "DELETE FROM foo WHERE id = '%s'" % identifier
 ```
 
-### References
+## References
 * [B608: Test for SQL injection](https://bandit.readthedocs.io/en/latest/plugins/b608_hardcoded_sql_expressions.html)
 * [psycopg3: Server-side binding](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html#server-side-binding)

docs/rules/implicit-namespace-package.md

@@ -2,10 +2,10 @@
 
 Derived from the **flake8-no-pep420** linter.
 
-### What it does
+## What it does
 Checks for packages that are missing an `__init__.py` file.
 
-### Why is this bad?
+## Why is this bad?
 Python packages are directories that contain a file named `__init__.py`.
 The existence of this file indicates that the directory is a Python
 package, and so it can be imported the same way a module can be

docs/rules/missing-required-import.md

@@ -4,16 +4,16 @@ Derived from the **isort** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Adds any required imports, as specified by the user, to the top of the file.
 
-### Why is this bad?
+## Why is this bad?
 In some projects, certain imports are required to be present in all files. For
 example, some projects assume that `from __future__ import annotations` is enabled,
 and thus require that import to be present in all files. Omitting a "required" import
 (as specified by the user) can cause errors or unexpected behavior.
 
-### Example
+## Example
 ```python
 import typing
 ```

docs/rules/missing-return-type-class-method.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that class methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 class Foo:
     @classmethod

docs/rules/missing-return-type-private-function.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that private functions and methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 def _add(a, b):
     return a + b

docs/rules/missing-return-type-public-function.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that public functions and methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 def add(a, b):
     return a + b

docs/rules/missing-return-type-special-method.md

@@ -4,11 +4,11 @@ Derived from the **flake8-annotations** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
 return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
@@ -23,7 +23,7 @@ or `ruff.toml` file:
 mypy-init-return = true
 ```
 
-### Example
+## Example
 ```python
 class Foo:
     def __init__(self, x: int):

docs/rules/missing-return-type-static-method.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that static methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 class Foo:
     @staticmethod

docs/rules/missing-type-args.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function `*args` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(*args):
     ...

docs/rules/missing-type-cls.md

@@ -2,10 +2,10 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that class method `cls` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
@@ -13,7 +13,7 @@ any provided arguments match expectation.
 Note that many type checkers will infer the type of `cls` automatically, so this
 annotation is not strictly necessary.
 
-### Example
+## Example
 ```python
 class Foo:
     @classmethod

docs/rules/missing-type-function-argument.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(x):
     ...

docs/rules/missing-type-kwargs.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function `**kwargs` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(**kwargs):
     ...

docs/rules/missing-type-self.md

@@ -2,10 +2,10 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that instance method `self` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
@@ -13,7 +13,7 @@ any provided arguments match expectation.
 Note that many type checkers will infer the type of `self` automatically, so this
 annotation is not strictly necessary.
 
-### Example
+## Example
 ```python
 class Foo:
     def bar(self):

docs/rules/prefix-type-params.md

@@ -2,15 +2,15 @@
 
 Derived from the **flake8-pyi** linter.
 
-### What it does
+## What it does
 Checks that type `TypeVar`, `ParamSpec`, and `TypeVarTuple` definitions in
 stubs are prefixed with `_`.
 
-### Why is this bad?
+## Why is this bad?
 By prefixing type parameters with `_`, we can avoid accidentally exposing
 names internal to the stub.
 
-### Example
+## Example
 ```python
 from typing import TypeVar
 

docs/rules/raise-vanilla-class.md

@@ -2,10 +2,10 @@
 
 Derived from the **tryceratops** linter.
 
-### What it does
+## What it does
 Checks for code that raises `Exception` directly.
 
-### Why is this bad?
+## Why is this bad?
 Handling such exceptions requires the use of `except Exception`, which
 captures _any_ raised exception, including failed assertions,
 division by zero, and more.
@@ -14,8 +14,8 @@ Prefer to raise your own exception, or a more specific built-in
 exception, so that you can avoid over-capturing exceptions that you
 don't intend to handle.
 
-### Example
-```py
+## Example
+```python
 def main_function():
     if not cond:
         raise Exception()
@@ -29,7 +29,7 @@ def consumer_func():
 ```
 
 Use instead:
-```py
+```python
 def main_function():
     if not cond:
         raise CustomException()
@@ -41,4 +41,5 @@ def consumer_func():
     except CustomException:
         logger.error("Main function failed")
     except Exception:
-        logger.error("Oops")
+        logger.error("Oops")
+```

docs/rules/unconventional-import-alias.md

@@ -2,11 +2,11 @@
 
 Derived from the **flake8-import-conventions** linter.
 
-### What it does
+## What it does
 Checks for imports that are typically imported using a common convention,
 like `import pandas as pd`, and enforces that convention.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use a common convention for imports to make your code
 more readable and idiomatic.
 
@@ -14,7 +14,7 @@ For example, `import pandas as pd` is a common
 convention for importing the `pandas` library, and users typically expect
 Pandas to be aliased as `pd`.
 
-### Example
+## Example
 ```python
 import pandas
 ```

docs/rules/unsorted-imports.md

@@ -4,14 +4,14 @@ Derived from the **isort** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 De-duplicates, groups, and sorts imports based on the provided `isort` settings.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use a common convention for imports to make your code
 more readable and idiomatic.
 
-### Example
+## Example
 ```python
 import pandas
 import numpy as np

docs/rules/yield-in-init.md

@@ -2,11 +2,11 @@
 
 Derived from the **Pylint** linter.
 
-### What it does
+## What it does
 Checks for `__init__` methods that are turned into generators by the
 inclusion of `yield` or `yield from` expressions.
 
-### Why is this bad?
+## Why is this bad?
 The `__init__` method is the constructor for a given Python class,
 responsible for initializing, rather than creating, new objects.
 
@@ -14,12 +14,12 @@ The `__init__` method has to return `None`. By including a `yield` or
 `yield from` expression in an `__init__`, the method will return a
 generator object when called at runtime, resulting in a runtime error.
 
-### Example
+## Example
 ```python
 class InitIsGenerator:
     def __init__(self, i):
         yield i
 ```
 
-### References
+## References
 * [`py-init-method-is-generator`](https://codeql.github.com/codeql-query-help/python/py-init-method-is-generator/)

ruff.schema.json

@@ -938,7 +938,7 @@
           ]
         },
         "force-wrap-aliases": {
-          "description": "Force `import from` statements with multiple members and at least one alias (e.g., `import A as B`) to wrap such that every line contains exactly one member. For example, this formatting would be retained, rather than condensing to a single line:\n\n```py from .utils import ( test_directory as test_directory, test_id as test_id ) ```\n\nNote that this setting is only effective when combined with `combine-as-imports = true`. When `combine-as-imports` isn't enabled, every aliased `import from` will be given its own line, in which case, wrapping is not necessary.",
+          "description": "Force `import from` statements with multiple members and at least one alias (e.g., `import A as B`) to wrap such that every line contains exactly one member. For example, this formatting would be retained, rather than condensing to a single line:\n\n```python from .utils import ( test_directory as test_directory, test_id as test_id ) ```\n\nNote that this setting is only effective when combined with `combine-as-imports = true`. When `combine-as-imports` isn't enabled, every aliased `import from` will be given its own line, in which case, wrapping is not necessary.",
           "type": [
             "boolean",
             "null"