ruff_python_formatter: light refactoring of code snippet formatting i…

…n docstrings (#8950)

In the source of working on #8859, I made a number of smallish refactors
to how code snippet formatting works. Most or all of these were
motivated by writing in support for reStructuredText blocks. They have
some fundamentally different requirements than doctests, and there are a
lot more ways for reStructuredText blocks to become invalid.

(Commit-by-commit review is recommended as the commit messages provide
further context on each change. I split this off from ongoing work to
make review more manageable.)

crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.py

@@ -1,3 +1,12 @@
+###############################################################################
+# DOCTEST CODE EXAMPLES
+#
+# This section shows examples of docstrings that contain code snippets in
+# Python's "doctest" format.
+#
+# See: https://docs.python.org/3/library/doctest.html
+###############################################################################
+
 # The simplest doctest to ensure basic formatting works.
 def doctest_simple():
     """