Skip to content

bpo-36675: Doc: Reveal doctest directives #23620

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 15, 2020
Merged

bpo-36675: Doc: Reveal doctest directives #23620

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eb7fcb8
Doc: Reveal doctest directives.
JulienPalard Dec 2, 2020
ac88608
A newer Sphinx is required to have no-trim-doctest-flags.
JulienPalard Dec 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .azure-pipelines/docs-steps.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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') }}:
Expand All @@ -31,7 +31,7 @@ steps:
- ${{ if eq(parameters.upload, 'true') }}:
- task: PublishBuildArtifacts@1
displayName: 'Publish docs'

inputs:
PathToPublish: '$(build.sourcesDirectory)/Doc/build'
ArtifactName: docs
Expand Down
54 changes: 37 additions & 17 deletions Doc/library/doctest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

.. doctest::
:no-trim-doctest-flags:

>>> print(list(range(20))) # doctest: +ELLIPSIS
>>> 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:

.. doctest::
:no-trim-doctest-flags:

>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
>>> 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
Expand Down Expand Up @@ -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

.. doctest::

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps

Suggested change
:no-trim-doctest-flags:

is missing here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rendered docs doesn't show the doctest directive in this case.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's better to keep it hidden in this case. The case is:

>>> id(1.0) # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()   # the default repr() for instances embeds an address  
<C object at 0x00AC18F0>

the comment in the case is true: it's expected to fail. If we reveal the hidden doctest: +SKIP it's no longer expected to fail, the comment becomes erroneous.

The point of this example is to demo usefull cases for +ELLIPSIS, not +SKIP.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, ok :)

>>> id(1.0) # certain to fail some of the time
>>> 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::
.. doctest::
:no-trim-doctest-flags:

>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
>>> 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,
Expand Down