changeset: 79432:18d927fb8671 branch: 2.7 parent: 79429:662fb4bd5f84 user: Nick Coghlan date: Wed Oct 03 13:48:17 2012 +0530 files: Doc/library/doctest.rst description: Issue #12947: Better workaround for the problem with doctest directives being stripped from code examples that are intended to illustrate those directives diff -r 662fb4bd5f84 -r 18d927fb8671 Doc/library/doctest.rst --- a/Doc/library/doctest.rst Wed Oct 03 12:18:23 2012 +0530 +++ b/Doc/library/doctest.rst Wed Oct 03 13:48:17 2012 +0530 @@ -681,14 +681,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 range(20) #doctest: +NORMALIZE_WHITESPACE [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, @@ -697,18 +698,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:: - ->>> print range(20) # doctest:+ELLIPSIS +so: + +.. code-block:: text + +>>> print 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 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 range(20) # doctest: +ELLIPSIS ... # doctest: +NORMALIZE_WHITESPACE @@ -716,7 +724,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 range(5) + range(10,20) + range(30,40) + range(50,60) ... # doctest: +ELLIPSIS