changeset: 79433:d93a59a0a984 branch: 3.3 parent: 79430:679b3e3aadae user: Nick Coghlan date: Wed Oct 03 13:52:48 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 679b3e3aadae -r d93a59a0a984 Doc/library/doctest.rst --- a/Doc/library/doctest.rst Wed Oct 03 12:21:44 2012 +0530 +++ b/Doc/library/doctest.rst Wed Oct 03 13:52:48 2012 +0530 @@ -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