From 799e7bb1526b8ff216169ed890cea8455ab0b8b9 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 13 Oct 2025 12:36:58 +0200 Subject: [PATCH 1/4] 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. --- Doc/faq/design.rst | 4 +- Doc/howto/functional.rst | 2 +- Doc/library/decimal.rst | 40 +++++++++---------- Doc/library/random.rst | 2 +- Doc/library/ssl.rst | 6 +-- Doc/reference/compound_stmts.rst | 8 ++-- Doc/whatsnew/3.4.rst | 2 +- ...-10-13-12-42-38.gh-issue-139257.Bs4NbU.rst | 1 + 8 files changed, 33 insertions(+), 32 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-13-12-42-38.gh-issue-139257.Bs4NbU.rst diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index ac0aa81e56bb07..1f47651f964dff 100644 --- a/Doc/faq/design.rst +++ b/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 diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 053558e389030a..8437ad0dc696b2 100644 --- a/Doc/howto/functional.rst +++ b/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 diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 0b99a832405549..e1defa679cb081 100644 --- a/Doc/library/decimal.rst +++ b/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 `_ library for arbitrary precision correctly rounded decimal floating-point arithmetic [#]_. diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 4e55e301b89095..aa79b70df5554d 100644 --- a/Doc/library/random.rst +++ b/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. diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 5b59a0698e4c42..f4a644cc98d7f7 100644 --- a/Doc/library/ssl.rst +++ b/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 `_ IANA diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 6521b4bee50758..06fe32e79a64e3 100644 --- a/Doc/reference/compound_stmts.rst +++ b/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 diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index 59afd6520c418f..31ffc3a2bc1eb5 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -2,7 +2,7 @@ What's New In Python 3.4 **************************** -:Author: R. David Murray (Editor) +:Author: R\. David Murray (Editor) .. Rules for maintenance: diff --git a/Misc/NEWS.d/next/Documentation/2025-10-13-12-42-38.gh-issue-139257.Bs4NbU.rst b/Misc/NEWS.d/next/Documentation/2025-10-13-12-42-38.gh-issue-139257.Bs4NbU.rst new file mode 100644 index 00000000000000..509c866312f3ac --- /dev/null +++ b/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. From 220e71a1d8beff48d9100843a30078a8b930ecd4 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 13 Oct 2025 13:02:21 +0200 Subject: [PATCH 2/4] Replace the monkey patch to disable roman lists with an exception We don't have a single clean method to disable roman lists across docutils versions, but we can blow up the bulid cleanly... --- Doc/tools/extensions/pyspecific.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index f5451adb37b0b4..6a66195d3cc463 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -24,12 +24,17 @@ # Used in conf.py and updated here by python/release-tools/run_release.py SOURCE_URI = 'https://github.com/python/cpython/tree/main/%s' -# monkey-patch reST parser to disable alphabetic and roman enumerated lists +# monkey-patch reST parser to detect any alphabetic and roman enumerated lists +# that need escaping. Sadly we don't get a location to point to. from docutils.parsers.rst.states import Body +def disabled_converter(x): + raise Exception("Detected an alphabetic or Roman enumerated list. " + "It needs to be escaped.") + Body.enum.converters['loweralpha'] = \ Body.enum.converters['upperalpha'] = \ Body.enum.converters['lowerroman'] = \ - Body.enum.converters['upperroman'] = lambda x: None + Body.enum.converters['upperroman'] = disabled_converter class PyAwaitableMixin(object): From 85a56889360910ad477808d0f16278769097bc88 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Wed, 15 Oct 2025 16:27:33 +0200 Subject: [PATCH 3/4] Use an explicitly named link Docutils 0.22 does not allow referencing a link that was implicitly named earlier in the document, it complains: ERROR: Duplicate target name, cannot be used as a unique reference: "basic authentication". --- Doc/howto/urllib2.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst index d79d1abe8d0577..2ad93f4450ba41 100644 --- a/Doc/howto/urllib2.rst +++ b/Doc/howto/urllib2.rst @@ -15,9 +15,11 @@ Introduction You may also find useful the following article on fetching web resources with Python: - * `Basic Authentication `_ + * `Basic Authentication`_ - A tutorial on *Basic Authentication*, with examples in Python. + A tutorial on *Basic Authentication*, with examples in Python. + +.. _Basic Authentication: https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml **urllib.request** is a Python module for fetching URLs (Uniform Resource Locators). It offers a very simple interface, in the form of From 8e6c0cc52c725a739c2683f3ef27452d6418535a Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Wed, 15 Oct 2025 16:34:06 +0200 Subject: [PATCH 4/4] Render the FAQ local tables of contents for all media Docutils 0.22 doesn't allow the contents directive to be used within an only directive, it complains: ERROR: The "contents" directive may not be used within topics or body elements. --- Doc/faq/design.rst | 4 +--- Doc/faq/extending.rst | 4 +--- Doc/faq/general.rst | 4 +--- Doc/faq/gui.rst | 4 +--- Doc/faq/library.rst | 4 +--- Doc/faq/programming.rst | 4 +--- Doc/faq/windows.rst | 4 +--- 7 files changed, 7 insertions(+), 21 deletions(-) diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 1f47651f964dff..f76b1139195b07 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -2,9 +2,7 @@ Design and History FAQ ====================== -.. only:: html - - .. contents:: +.. contents:: Why does Python use indentation for grouping of statements? diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 1d5abed2317b0c..beb7ec30f93b89 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -2,9 +2,7 @@ Extending/Embedding FAQ ======================= -.. only:: html - - .. contents:: +.. contents:: .. highlight:: c diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 578777d7f23621..6a50a321fab68b 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -4,9 +4,7 @@ General Python FAQ ================== -.. only:: html - - .. contents:: +.. contents:: General Information diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst index cfa60feceb31b7..c837216f5cecdb 100644 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@ -4,9 +4,7 @@ Graphic User Interface FAQ ========================== -.. only:: html - - .. contents:: +.. contents:: .. XXX need review for Python 3. diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index d8d75ca6f2ec96..04dce2f12745d5 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -4,9 +4,7 @@ Library and Extension FAQ ========================= -.. only:: html - - .. contents:: +.. contents:: General Library Questions ========================= diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 6f9dfa8616ed44..236533b7313f2c 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -4,9 +4,7 @@ Programming FAQ =============== -.. only:: html - - .. contents:: +.. contents:: General Questions ================= diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index c0c92fdbbc84d1..4346e2a03ee125 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -8,9 +8,7 @@ Python on Windows FAQ ===================== -.. only:: html - - .. contents:: +.. contents:: .. XXX need review for Python 3. XXX need review for Windows Vista/Seven?