bpo-36675: Doc: Reveal doctest directives (GH-23620)
This commit is contained in:
parent
3ca2b8fd75
commit
c8a10d2fab
|
@ -12,7 +12,7 @@ steps:
|
|||
inputs:
|
||||
versionSpec: '>=3.6'
|
||||
|
||||
- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
|
||||
- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
|
||||
displayName: 'Install build dependencies'
|
||||
|
||||
- ${{ if ne(parameters.latex, 'true') }}:
|
||||
|
@ -31,7 +31,7 @@ steps:
|
|||
- ${{ if eq(parameters.upload, 'true') }}:
|
||||
- task: PublishBuildArtifacts@1
|
||||
displayName: 'Publish docs'
|
||||
|
||||
|
||||
inputs:
|
||||
PathToPublish: '$(build.sourcesDirectory)/Doc/build'
|
||||
ArtifactName: docs
|
||||
|
|
|
@ -719,36 +719,51 @@ above.
|
|||
An example's doctest directives modify doctest's behavior for that single
|
||||
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
|
||||
|
||||
For example, this test passes::
|
||||
For example, this test passes:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> 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::
|
||||
so:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +ELLIPSIS
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +ELLIPSIS
|
||||
[0, 1, ..., 18, 19]
|
||||
|
||||
Multiple directives can be used on a single physical line, separated by
|
||||
commas::
|
||||
commas:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> 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:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +ELLIPSIS
|
||||
... # doctest: +NORMALIZE_WHITESPACE
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> print(list(range(20))) # doctest: +ELLIPSIS
|
||||
... # doctest: +NORMALIZE_WHITESPACE
|
||||
[0, 1, ..., 18, 19]
|
||||
|
||||
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:
|
||||
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
|
||||
... # doctest: +ELLIPSIS
|
||||
|
@ -793,18 +808,23 @@ instead. Another is to do ::
|
|||
|
||||
There are others, but you get the idea.
|
||||
|
||||
Another bad idea is to print things that embed an object address, like ::
|
||||
Another bad idea is to print things that embed an object address, like
|
||||
|
||||
>>> id(1.0) # certain to fail some of the time
|
||||
.. doctest::
|
||||
|
||||
>>> id(1.0) # certain to fail some of the time # doctest: +SKIP
|
||||
7948648
|
||||
>>> class C: pass
|
||||
>>> C() # the default repr() for instances embeds an address
|
||||
<__main__.C instance at 0x00AC18F0>
|
||||
>>> C() # the default repr() for instances embeds an address # doctest: +SKIP
|
||||
<C object at 0x00AC18F0>
|
||||
|
||||
The :const:`ELLIPSIS` directive gives a nice approach for the last example::
|
||||
The :const:`ELLIPSIS` directive gives a nice approach for the last example:
|
||||
|
||||
>>> C() #doctest: +ELLIPSIS
|
||||
<__main__.C instance at 0x...>
|
||||
.. doctest::
|
||||
:no-trim-doctest-flags:
|
||||
|
||||
>>> C() # doctest: +ELLIPSIS
|
||||
<C object at 0x...>
|
||||
|
||||
Floating-point numbers are also subject to small output variations across
|
||||
platforms, because Python defers to the platform C library for float formatting,
|
||||
|
|
Loading…
Reference in New Issue