[Python-checkins] cpython (3.3): Issue #12947: Better workaround for the problem with doctest directives being

[nick.coghlan]

http://hg.python.org/cpython/rev/d93a59a0a984
changeset:   79433:d93a59a0a984
branch:      3.3
parent:      79430:679b3e3aadae
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Wed Oct 03 13:52:48 2012 +0530
summary:
  Issue #12947: Better workaround for the problem with doctest directives being stripped from code examples that are intended to illustrate those directives

files:
  Doc/library/doctest.rst |  34 ++++++++++++++++++----------
  1 files changed, 22 insertions(+), 12 deletions(-)


diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -651,14 +651,15 @@
 example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.
 
 .. note::
-   Due to an `unfortunate bug`_ in our documentation publishing process, the
-   directives in the following examples are not being displayed in the
-   rendered HTML version. Please use the "Show Source" link in the sidebar
-   to view the details of the directive usage examples.
-
-   .. _unfortunate bug: http://bugs.python.org/issue12947
-
-For example, this test passes::
+   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.
+
+   .. _unfortunate limitation: http://bugs.python.org/issue12947
+
+For example, this test passes:
+
+.. code-block:: text
 
    >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
    [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
@@ -667,18 +668,25 @@
 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:
+
+.. code-block:: text
 
    >>> print(list(range(20))) # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]
 
-Multiple directives can be used on a single physical line, separated by commas::
+Multiple directives can be used on a single physical line, separated by
+commas:
+
+.. code-block:: text
 
    >>> 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:
+
+.. code-block:: text
 
    >>> print(list(range(20))) # doctest: +ELLIPSIS
    ...                        # doctest: +NORMALIZE_WHITESPACE
@@ -686,7 +694,9 @@
 
 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:
+
+.. code-block:: text
 
    >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
    ... # doctest: +ELLIPSIS

-- 
Repository URL: http://hg.python.org/cpython