From fb38c64690a459d1ee0799d1e22b7911dd97a65d Mon Sep 17 00:00:00 2001
From: Julien Palard <julien@palard.fr>
Date: Tue, 15 Dec 2020 17:23:03 +0100
Subject: [PATCH] bpo-36675: Doc: Reveal doctest directives (GH-23620)

---
 .azure-pipelines/docs-steps.yml |  4 +--
 Doc/library/doctest.rst         | 54 ++++++++++++++++++++++-----------
 2 files changed, 39 insertions(+), 19 deletions(-)

diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml
index 55c38611b95c81..8e72baf2b12fe1 100644
--- a/.azure-pipelines/docs-steps.yml
+++ b/.azure-pipelines/docs-steps.yml
@@ -12,7 +12,7 @@ steps:
   inputs:
     versionSpec: '>=3.6'
 
-- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
+- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
   displayName: 'Install build dependencies'
 
 - ${{ if ne(parameters.latex, 'true') }}:
@@ -31,7 +31,7 @@ steps:
 - ${{ if eq(parameters.upload, 'true') }}:
   - task: PublishBuildArtifacts@1
     displayName: 'Publish docs'
-  
+
     inputs:
       PathToPublish: '$(build.sourcesDirectory)/Doc/build'
       ArtifactName: docs
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index a77322f83acbde..42ad0c9f06e237 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -719,36 +719,51 @@ above.
 An example's doctest directives modify doctest's behavior for that single
 example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.
 
-For example, this test passes::
+For example, this test passes:
 
-   >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
    [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
    10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
 
 Without the directive it would fail, both because the actual output doesn't have
 two blanks before the single-digit list elements, and because the actual output
 is on a single line.  This test also passes, and also requires a directive to do
-so::
+so:
+
+.. doctest::
+   :no-trim-doctest-flags:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]
 
 Multiple directives can be used on a single physical line, separated by
-commas::
+commas:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]
 
 If multiple directive comments are used for a single example, then they are
-combined::
+combined:
+
+.. doctest::
+   :no-trim-doctest-flags:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS
-   ...                        # doctest: +NORMALIZE_WHITESPACE
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS
+   ...                         # doctest: +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]
 
 As the previous example shows, you can add ``...`` lines to your example
 containing only directives.  This can be useful when an example is too long for
-a directive to comfortably fit on the same line::
+a directive to comfortably fit on the same line:
+
+.. doctest::
+   :no-trim-doctest-flags:
 
    >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
    ... # doctest: +ELLIPSIS
@@ -793,18 +808,23 @@ instead.  Another is to do ::
 
 There are others, but you get the idea.
 
-Another bad idea is to print things that embed an object address, like ::
+Another bad idea is to print things that embed an object address, like
+
+.. doctest::
 
-   >>> id(1.0) # certain to fail some of the time
+   >>> id(1.0) # certain to fail some of the time  # doctest: +SKIP
    7948648
    >>> class C: pass
-   >>> C()   # the default repr() for instances embeds an address
-   <__main__.C instance at 0x00AC18F0>
+   >>> C()   # the default repr() for instances embeds an address  # doctest: +SKIP
+   <C object at 0x00AC18F0>
+
+The :const:`ELLIPSIS` directive gives a nice approach for the last example:
 
-The :const:`ELLIPSIS` directive gives a nice approach for the last example::
+.. doctest::
+   :no-trim-doctest-flags:
 
-   >>> C() #doctest: +ELLIPSIS
-   <__main__.C instance at 0x...>
+   >>> C()  # doctest: +ELLIPSIS
+   <C object at 0x...>
 
 Floating-point numbers are also subject to small output variations across
 platforms, because Python defers to the platform C library for float formatting,