From 82814624bf4049e4692a85d7973e62e469e6e5f5 Mon Sep 17 00:00:00 2001
From: Zachary Ware <zach@python.org>
Date: Sat, 30 Jul 2022 17:21:08 -0500
Subject: [PATCH] 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
---
 .github/workflows/doc.yml |  2 +-
 Doc/conf.py               |  5 +++++
 Doc/library/math.rst      |  6 +++---
 Doc/library/nntplib.rst   | 17 +++++++++++++++++
 Doc/library/turtle.rst    |  2 +-
 Doc/whatsnew/3.2.rst      |  4 ++--
 6 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index e06f21671b5a5a..d95d089ed66755 100644
--- 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 0c7deb59d130dc..bf0af6a663c8b6 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -22,6 +22,11 @@
     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 6d9a992f731316..e338959ffbe4bf 100644
--- 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 2a996e451bf7c5..5aad44d929e871 100644
--- 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 17bf8829a9fed1..5add61c759ea8e 100644
--- 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 31f2ea85ffd233..c7b42ef0ed739c 100644
--- 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'