Doctest cleanups (GH-95436)

* GHA: Don't hide doctest output

* Enable doctests in math.rst

* Squash warnings in nntplib.rst doctests

* Squash warning in turtle.rst doctest

* Squash warnings in whatsnew/3.2.rst doctests

* Treat warnings as errors in Doc/ doctests

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index e06f21671b5a5a7bc38157cfafc7a16064e1a000..d95d089ed66755e274c80e44eec4cc30419439b3 100644 (file)
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -78,4 +78,4 @@ jobs:
       run: make -C Doc/ PYTHON=../python venv
     # Use "xvfb-run" since some doctest tests open GUI windows
     - name: 'Run documentation doctest'
-      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" doctest
+      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="-W --keep-going" doctest

diff --git a/Doc/conf.py b/Doc/conf.py
index 0c7deb59d130dc3e643d78e6c123a6f082feb0d8..bf0af6a663c8b65bef11c5c4abfe72d7667a47d4 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -22,6 +22,11 @@ try:
     import _tkinter
 except ImportError:
     _tkinter = None
+# Treat warnings as errors, done here to prevent warnings in Sphinx code from
+# causing spurious test failures.
+import warnings
+warnings.simplefilter('error')
+del warnings
 '''
 
 manpages_url = 'https://manpages.debian.org/{path}'

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 6d9a992f731316c84cceeb8a97eae27da5787282..e338959ffbe4bf040b95a7850e6764031bf8f7ef 100644 (file)
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -108,7 +108,7 @@ Number-theoretic and representation functions
 .. function:: fsum(iterable)
 
    Return an accurate floating point sum of values in the iterable.  Avoids
-   loss of precision by tracking multiple intermediate partial sums::
+   loss of precision by tracking multiple intermediate partial sums:
 
         >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
         0.9999999999999999
@@ -371,7 +371,7 @@ Power and logarithmic functions
    logarithms.  For small floats *x*, the subtraction in ``exp(x) - 1``
    can result in a `significant loss of precision
    <https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1`
-   function provides a way to compute this quantity to full precision::
+   function provides a way to compute this quantity to full precision:
 
       >>> from math import exp, expm1
       >>> exp(1e-5) - 1  # gives result accurate to 11 places
@@ -654,7 +654,7 @@ Constants
    not considered to equal to any other numeric value, including themselves. To check
    whether a number is a NaN, use the :func:`isnan` function to test
    for NaNs instead of ``is`` or ``==``.
-   Example::
+   Example:
 
       >>> import math
       >>> math.nan == math.nan

diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
index 2a996e451bf7c535c81f17b05c571e754f3ccc08..5aad44d929e87168848b97d04736016b250082a0 100644 (file)
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -14,6 +14,23 @@
 .. deprecated:: 3.11
    The :mod:`nntplib` module is deprecated (see :pep:`594` for details).
 
+.. testsetup::
+
+   import warnings
+   with warnings.catch_warnings():
+       warnings.simplefilter('ignore', category=DeprecationWarning)
+       import nntplib
+
+.. testcleanup::
+
+   try:
+       s.quit()
+   except NameError:
+       pass
+   import sys
+   # Force a warning if any other file imports nntplib
+   sys.modules.pop('nntplib')
+
 --------------
 
 This module defines the class :class:`NNTP` which implements the client side of

diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 17bf8829a9fed145ba0579ba21806b380da38020..5add61c759ea8ec4a40b9ca324955af3caafa53c 100644 (file)
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -1279,7 +1279,7 @@ Appearance
    (direction of movement).
 
    .. doctest::
-      :skipif: _tkinter is None
+      :skipif: _tkinter is None or 'always; deprecated method'
 
       >>> turtle.reset()
       >>> turtle.shape("circle")

diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 31f2ea85ffd233136349c94d4bc7a2693c1eee98..c7b42ef0ed739cf146691685679adf8f951739f3 100644 (file)
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -322,7 +322,7 @@ aspects that are visible to the programmer:
 * The tag that is unique to each interpreter is accessible from the :mod:`imp`
   module:
 
-   >>> import imp
+   >>> import imp # doctest: +SKIP
    >>> imp.get_tag() # doctest: +SKIP
    'cpython-32'
 
@@ -330,7 +330,7 @@ aspects that are visible to the programmer:
   be smarter.  It is no longer sufficient to simply strip the "c" from a ".pyc"
   filename.  Instead, use the new functions in the :mod:`imp` module:
 
-  >>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc')
+  >>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc') # doctest: +SKIP
   'c:/py32/lib/collections.py'
   >>> imp.cache_from_source('c:/py32/lib/collections.py') # doctest: +SKIP
   'c:/py32/lib/__pycache__/collections.cpython-32.pyc'