Issue #12947: revert earlier workaround and use a monkey-patch to enable showing doctest directives only in the doctest docs.

Doc/library/doctest.rst

@@ -1,3 +1,5 @@
+:keepdoctest:
+
 :mod:`doctest` --- Test interactive Python examples
 ===================================================
 
@@ -674,43 +676,28 @@ above.
 An example's doctest directives modify doctest's behavior for that single
 example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.
 
-.. note::
-   Due to an `unfortunate limitation`_ of our current documentation
-   publishing process, syntax highlighting has been disabled in the examples
-   below in order to ensure the doctest directives are correctly displayed.
+For example, this test passes::
 
-   .. _unfortunate limitation: http://bugs.python.org/issue12947
-
-For example, this test passes:
-
-.. code-block:: text
-
-   >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
+   >>> 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:
-
-.. code-block:: text
+so::
 
    >>> print(list(range(20))) # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]
 
 Multiple directives can be used on a single physical line, separated by
-commas:
-
-.. code-block:: text
+commas::
 
    >>> 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:
-
-.. code-block:: text
+combined::
 
    >>> print(list(range(20))) # doctest: +ELLIPSIS
    ...                        # doctest: +NORMALIZE_WHITESPACE
@@ -718,9 +705,7 @@ combined:
 
 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:
-
-.. code-block:: text
+a directive to comfortably fit on the same line::
 
    >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
    ... # doctest: +ELLIPSIS

Doc/tools/sphinxext/pyspecific.py

@@ -33,9 +33,38 @@ def new_visit_versionmodified(self, node):
     self.body.append('<span class="versionmodified">%s</span> ' % text)
 
 from sphinx.writers.html import HTMLTranslator
+from sphinx.writers.latex import LaTeXTranslator
 from sphinx.locale import versionlabels
 HTMLTranslator.visit_versionmodified = new_visit_versionmodified
+HTMLTranslator.visit_versionmodified = new_visit_versionmodified
 
+# monkey-patch HTML and LaTeX translators to keep doctest blocks in the
+# doctest docs themselves
+orig_visit_literal_block = HTMLTranslator.visit_literal_block
+def new_visit_literal_block(self, node):
+    meta = self.builder.env.metadata[self.builder.current_docname]
+    old_trim_doctest_flags = self.highlighter.trim_doctest_flags
+    if 'keepdoctest' in meta:
+        self.highlighter.trim_doctest_flags = False
+    try:
+        orig_visit_literal_block(self, node)
+    finally:
+        self.highlighter.trim_doctest_flags = old_trim_doctest_flags
+
+HTMLTranslator.visit_literal_block = new_visit_literal_block
+
+orig_depart_literal_block = LaTeXTranslator.depart_literal_block
+def new_depart_literal_block(self, node):
+    meta = self.builder.env.metadata[self.curfilestack[-1]]
+    old_trim_doctest_flags = self.highlighter.trim_doctest_flags
+    if 'keepdoctest' in meta:
+        self.highlighter.trim_doctest_flags = False
+    try:
+        orig_depart_literal_block(self, node)
+    finally:
+        self.highlighter.trim_doctest_flags = old_trim_doctest_flags
+
+LaTeXTranslator.depart_literal_block = new_depart_literal_block
 
 # Support for marking up and linking to bugs.python.org issues