add support for formatting reStructuredText code snippets (#9003)

(This is not possible to actually use until
https://github.com/astral-sh/ruff/pull/8854 is merged.)

ruff_python_formatter: add reStructuredText docstring formatting support

This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
[common
practice](https://github.com/adamchainz/blacken-docs/issues/195).

That is, literal blocks like this:

```
def example():
    """
    Here's an example::

        foo( 1 )

    All done.
    """
    pass
```

Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:


```
def example():
    """
    Here's an example:

    .. code-block:: python

        foo( 1 )

    All done.
    """
    pass
```

When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.

A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.

I recommend working through this PR commit-by-commit. There is in
particular a somewhat gnarly refactoring before reST support is added.

Closes #8859

crates/ruff_python_formatter/tests/normalizer.rs

@@ -60,7 +60,7 @@ impl Transformer for Normalizer {
     }
 
     fn visit_string_literal(&self, string_literal: &mut ast::StringLiteral) {
-        static STRIP_CODE_SNIPPETS: Lazy<Regex> = Lazy::new(|| {
+        static STRIP_DOC_TESTS: Lazy<Regex> = Lazy::new(|| {
             Regex::new(
                 r#"(?mx)
                     (
@@ -75,14 +75,27 @@ impl Transformer for Normalizer {
             )
             .unwrap()
         });
+        static STRIP_RST_BLOCKS: Lazy<Regex> = Lazy::new(|| {
+            // This is kind of unfortunate, but it's pretty tricky (likely
+            // impossible) to detect a reStructuredText block with a simple
+            // regex. So we just look for the start of a block and remove
+            // everything after it. Talk about a hammer.
+            Regex::new(r#"::(?s:.*)"#).unwrap()
+        });
 
         // Start by (1) stripping everything that looks like a code
         // snippet, since code snippets may be completely reformatted if
         // they are Python code.
-        string_literal.value = STRIP_CODE_SNIPPETS
+        string_literal.value = STRIP_DOC_TESTS
             .replace_all(
                 &string_literal.value,
-                "<CODE-SNIPPET: Removed by normalizer>\n",
+                "<DOCTEST-CODE-SNIPPET: Removed by normalizer>\n",
+            )
+            .into_owned();
+        string_literal.value = STRIP_RST_BLOCKS
+            .replace_all(
+                &string_literal.value,
+                "<RSTBLOCK-CODE-SNIPPET: Removed by normalizer>\n",
             )
             .into_owned();
         // Normalize a string by (2) stripping any leading and trailing space from each