bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282) · python/cpython@5c1f15b (original) (raw)

`@@ -719,51 +719,36 @@ above.

719

`An example's doctest directives modify doctest's behavior for that single

720

``` example. Use + to enable the named behavior, or - to disable it.


`721`

`721`

``

`722`

``

`-

For example, this test passes:

`

``

`722`

`+

For example, this test passes::

`

`723`

`723`

``

`724`

``

`-

.. doctest::

`

`725`

``

`-

:no-trim-doctest-flags:

`

`726`

``

`-`

`727`

``

`-

>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE

`

``

`724`

`+

>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE

`

`728`

`725`

` [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,

`

`729`

`726`

` 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]

`

`730`

`727`

``

`731`

`728`

`Without the directive it would fail, both because the actual output doesn't have

`

`732`

`729`

`two blanks before the single-digit list elements, and because the actual output

`

`733`

`730`

`is on a single line. This test also passes, and also requires a directive to do

`

`734`

``

`-

so:

`

`735`

``

`-`

`736`

``

`-

.. doctest::

`

`737`

``

`-

:no-trim-doctest-flags:

`

``

`731`

`+

so::

`

`738`

`732`

``

`739`

``

`-

>>> print(list(range(20))) # doctest: +ELLIPSIS

`

``

`733`

`+

>>> print(list(range(20))) # doctest: +ELLIPSIS

`

`740`

`734`

` [0, 1, ..., 18, 19]

`

`741`

`735`

``

`742`

`736`

`Multiple directives can be used on a single physical line, separated by

`

`743`

``

`-

commas:

`

``

`737`

`+

commas::

`

`744`

`738`

``

`745`

``

`-

.. doctest::

`

`746`

``

`-

:no-trim-doctest-flags:

`

`747`

``

`-`

`748`

``

`-

>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE

`

``

`739`

`+

>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE

`

`749`

`740`

` [0, 1, ..., 18, 19]

`

`750`

`741`

``

`751`

`742`

`If multiple directive comments are used for a single example, then they are

`

`752`

``

`-

combined:

`

`753`

``

`-`

`754`

``

`-

.. doctest::

`

`755`

``

`-

:no-trim-doctest-flags:

`

``

`743`

`+

combined::

`

`756`

`744`

``

`757`

``

`-

>>> print(list(range(20))) # doctest: +ELLIPSIS

`

`758`

``

`-

... # doctest: +NORMALIZE_WHITESPACE

`

``

`745`

`+

>>> print(list(range(20))) # doctest: +ELLIPSIS

`

``

`746`

`+

... # doctest: +NORMALIZE_WHITESPACE

`

`759`

`747`

` [0, 1, ..., 18, 19]

`

`760`

`748`

``

`761`

`749`

``` As the previous example shows, you can add ``...`` lines to your example

762

750

`containing only directives. This can be useful when an example is too long for

763

a directive to comfortably fit on the same line:

764

-

765

.. doctest::

766

:no-trim-doctest-flags:

751

a directive to comfortably fit on the same line::

767

752

768

753

` >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))

769

754

` ... # doctest: +ELLIPSIS

`@@ -808,23 +793,18 @@ instead. Another is to do ::

808

793

809

794

`There are others, but you get the idea.

810

795

811

Another bad idea is to print things that embed an object address, like

812

-

813

.. doctest::

796

Another bad idea is to print things that embed an object address, like ::

814

797

815

id(1.0) # certain to fail some of the time # doctest: +SKIP

798

id(1.0) # certain to fail some of the time

816

799

` 7948648

817

800

` >>> class C: pass

818

C() # the default repr() for instances embeds an address # doctest: +SKIP

819

820

-

821

`` -

The :const:ELLIPSIS directive gives a nice approach for the last example:

801

C() # the default repr() for instances embeds an address

802

<__main__.C instance at 0x00AC18F0>

822

803

823

.. doctest::

824

:no-trim-doctest-flags:

804

`` +

The :const:ELLIPSIS directive gives a nice approach for the last example::

825

805

826

C() # doctest: +ELLIPSIS

827

806

C() #doctest: +ELLIPSIS

807

<__main__.C instance at 0x...>

828

808

829

809

`Floating-point numbers are also subject to small output variations across

830

810

`platforms, because Python defers to the platform C library for float formatting,