gh-139257: docutils 0.22 support

Escape things that look like Roman numerals. Docutils 0.22 includes a
new roman-numeral interpreter that falls over some of our content.
Escape anything that causes trouble.

Python itself isn't using docutils 0.22 yet for its doc generation, but
some Linux distributions have updated to it.

Author: stefanor

Doc/faq/design.rst

@@ -170,14 +170,14 @@ Why does Python use methods for some functionality (e.g. list.index()) but funct
 
 As Guido said:
 
-    (a) For some operations, prefix notation just reads better than
+    \(a) For some operations, prefix notation just reads better than
     postfix -- prefix (and infix!) operations have a long tradition in
     mathematics which likes notations where the visuals help the
     mathematician thinking about a problem. Compare the easy with which we
     rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of
     doing the same thing using a raw OO notation.
 
-    (b) When I read code that says len(x) I *know* that it is asking for
+    \(b) When I read code that says len(x) I *know* that it is asking for
     the length of something. This tells me two things: the result is an
     integer, and the argument is some kind of container. To the contrary,
     when I read x.len(), I have to already know that x is some kind of

Doc/howto/functional.rst

@@ -4,7 +4,7 @@
   Functional Programming HOWTO
 ********************************
 
-:Author: A. M. Kuchling
+:Author: A\. M. Kuchling
 :Release: 0.32
 
 In this document, we'll take a tour of Python's features suitable for

Doc/library/decimal.rst

@@ -2100,20 +2100,20 @@ to work with the :class:`Decimal` class::
 Decimal FAQ
 -----------
 
-Q. It is cumbersome to type ``decimal.Decimal('1234.5')``.  Is there a way to
+Q\. It is cumbersome to type ``decimal.Decimal('1234.5')``.  Is there a way to
 minimize typing when using the interactive interpreter?
 
-A. Some users abbreviate the constructor to just a single letter:
+A\. Some users abbreviate the constructor to just a single letter:
 
    >>> D = decimal.Decimal
    >>> D('1.23') + D('3.45')
    Decimal('4.68')
 
-Q. In a fixed-point application with two decimal places, some inputs have many
+Q\. In a fixed-point application with two decimal places, some inputs have many
 places and need to be rounded.  Others are not supposed to have excess digits
 and need to be validated.  What methods should be used?
 
-A. The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal places. If
+A\. The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal places. If
 the :const:`Inexact` trap is set, it is also useful for validation:
 
    >>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')
@@ -2131,10 +2131,10 @@ the :const:`Inexact` trap is set, it is also useful for validation:
       ...
    Inexact: None
 
-Q. Once I have valid two place inputs, how do I maintain that invariant
+Q\. Once I have valid two place inputs, how do I maintain that invariant
 throughout an application?
 
-A. Some operations like addition, subtraction, and multiplication by an integer
+A\. Some operations like addition, subtraction, and multiplication by an integer
 will automatically preserve fixed point.  Others operations, like division and
 non-integer multiplication, will change the number of decimal places and need to
 be followed-up with a :meth:`~Decimal.quantize` step:
@@ -2166,21 +2166,21 @@ to handle the :meth:`~Decimal.quantize` step:
     >>> div(b, a)
     Decimal('0.03')
 
-Q. There are many ways to express the same value.  The numbers ``200``,
+Q\. There are many ways to express the same value.  The numbers ``200``,
 ``200.000``, ``2E2``, and ``.02E+4`` all have the same value at
 various precisions. Is there a way to transform them to a single recognizable
 canonical value?
 
-A. The :meth:`~Decimal.normalize` method maps all equivalent values to a single
+A\. The :meth:`~Decimal.normalize` method maps all equivalent values to a single
 representative:
 
    >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
    >>> [v.normalize() for v in values]
    [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
 
-Q. When does rounding occur in a computation?
+Q\. When does rounding occur in a computation?
 
-A. It occurs *after* the computation.  The philosophy of the decimal
+A\. It occurs *after* the computation.  The philosophy of the decimal
 specification is that numbers are considered exact and are created
 independent of the current context.  They can even have greater
 precision than current context.  Computations process with those
@@ -2198,10 +2198,10 @@ applied to the *result* of the computation::
    >>> pi + 0 - Decimal('0.00005').   # Intermediate values are rounded
    Decimal('3.1416')
 
-Q. Some decimal values always print with exponential notation.  Is there a way
+Q\. Some decimal values always print with exponential notation.  Is there a way
 to get a non-exponential representation?
 
-A. For some values, exponential notation is the only way to express the number
+A\. For some values, exponential notation is the only way to express the number
 of significant places in the coefficient.  For example, expressing
 ``5.0E+3`` as ``5000`` keeps the value constant but cannot show the
 original's two-place significance.
@@ -2216,9 +2216,9 @@ value unchanged:
     >>> remove_exponent(Decimal('5E+3'))
     Decimal('5000')
 
-Q. Is there a way to convert a regular float to a :class:`Decimal`?
+Q\. Is there a way to convert a regular float to a :class:`Decimal`?
 
-A. Yes, any binary floating-point number can be exactly expressed as a
+A\. Yes, any binary floating-point number can be exactly expressed as a
 Decimal though an exact conversion may take more precision than intuition would
 suggest:
 
@@ -2227,19 +2227,19 @@ suggest:
     >>> Decimal(math.pi)
     Decimal('3.141592653589793115997963468544185161590576171875')
 
-Q. Within a complex calculation, how can I make sure that I haven't gotten a
+Q\. Within a complex calculation, how can I make sure that I haven't gotten a
 spurious result because of insufficient precision or rounding anomalies.
 
-A. The decimal module makes it easy to test results.  A best practice is to
+A\. The decimal module makes it easy to test results.  A best practice is to
 re-run calculations using greater precision and with various rounding modes.
 Widely differing results indicate insufficient precision, rounding mode issues,
 ill-conditioned inputs, or a numerically unstable algorithm.
 
-Q. I noticed that context precision is applied to the results of operations but
+Q\. I noticed that context precision is applied to the results of operations but
 not to the inputs.  Is there anything to watch out for when mixing values of
 different precisions?
 
-A. Yes.  The principle is that all values are considered to be exact and so is
+A\. Yes.  The principle is that all values are considered to be exact and so is
 the arithmetic on those values.  Only the results are rounded.  The advantage
 for inputs is that "what you type is what you get".  A disadvantage is that the
 results can look odd if you forget that the inputs haven't been rounded:
@@ -2267,9 +2267,9 @@ Alternatively, inputs can be rounded upon creation using the
    >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
    Decimal('1.2345')
 
-Q. Is the CPython implementation fast for large numbers?
+Q\. Is the CPython implementation fast for large numbers?
 
-A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
+A\. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
 the decimal module integrate the high speed `libmpdec
 <https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html>`_ library for
 arbitrary precision correctly rounded decimal floating-point arithmetic [#]_.

Doc/library/random.rst

@@ -49,7 +49,7 @@ from sources provided by the operating system.
 
 .. seealso::
 
-   M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
+   M\. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
    equidistributed uniform pseudorandom number generator", ACM Transactions on
    Modeling and Computer Simulation Vol. 8, No. 1, January pp.3--30 1998.
 

Doc/library/ssl.rst

@@ -2961,13 +2961,13 @@ of TLS/SSL. Some new TLS 1.3 features are not yet available.
        Donald E., Jeffrey I. Schiller
 
    :rfc:`RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile <5280>`
-       D. Cooper
+       D\. Cooper
 
    :rfc:`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <5246>`
-       T. Dierks et. al.
+       T\. Dierks et. al.
 
    :rfc:`RFC 6066: Transport Layer Security (TLS) Extensions <6066>`
-       D. Eastlake
+       D\. Eastlake
 
    `IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_
        IANA

Doc/reference/compound_stmts.rst

@@ -1122,7 +1122,7 @@ subject value:
    If only keyword patterns are present, they are processed as follows,
    one by one:
 
-   I. The keyword is looked up as an attribute on the subject.
+   I\. The keyword is looked up as an attribute on the subject.
 
       * If this raises an exception other than :exc:`AttributeError`, the
         exception bubbles up.
@@ -1134,13 +1134,13 @@ subject value:
         pattern fails; if this succeeds, the match proceeds to the next keyword.
 
 
-   II. If all keyword patterns succeed, the class pattern succeeds.
+   II\. If all keyword patterns succeed, the class pattern succeeds.
 
    If any positional patterns are present, they are converted to keyword
    patterns using the :data:`~object.__match_args__` attribute on the class
    ``name_or_attr`` before matching:
 
-   I. The equivalent of ``getattr(cls, "__match_args__", ())`` is called.
+   I\. The equivalent of ``getattr(cls, "__match_args__", ())`` is called.
 
       * If this raises an exception, the exception bubbles up.
 
@@ -1158,7 +1158,7 @@ subject value:
 
       .. seealso:: :ref:`class-pattern-matching`
 
-   II. Once all positional patterns have been converted to keyword patterns,
+   II\. Once all positional patterns have been converted to keyword patterns,
        the match proceeds as if there were only keyword patterns.
 
    For the following built-in types the handling of positional subpatterns is

Doc/whatsnew/3.4.rst

@@ -2,7 +2,7 @@
   What's New In Python 3.4
 ****************************
 
-:Author: R. David Murray <[email protected]> (Editor)
+:Author: R\. David Murray <[email protected]> (Editor)
 
 .. Rules for maintenance:
 

Misc/NEWS.d/next/Documentation/2025-10-13-12-42-38.gh-issue-139257.Bs4NbU.rst

@@ -0,0 +1 @@
+Support building the documentation with docutils >= 0.22.