[Python-checkins] bpo-36675: Doc: Reveal doctest directives (GH-23620)
JulienPalard
webhook-mailer at python.org
Tue Dec 15 11:23:11 EST 2020
https://github.com/python/cpython/commit/c8a10d2fabff492ab352501c316baf5f2fc6510e
commit: c8a10d2fabff492ab352501c316baf5f2fc6510e
branch: master
author: Julien Palard <julien at palard.fr>
committer: JulienPalard <julien at palard.fr>
date: 2020-12-15T17:23:03+01:00
summary:
bpo-36675: Doc: Reveal doctest directives (GH-23620)
files:
M .azure-pipelines/docs-steps.yml
M Doc/library/doctest.rst
diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml
index 55c38611b95c8..8e72baf2b12fe 100644
--- a/.azure-pipelines/docs-steps.yml
+++ b/.azure-pipelines/docs-steps.yml
@@ -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 at 1
displayName: 'Publish docs'
-
+
inputs:
PathToPublish: '$(build.sourcesDirectory)/Doc/build'
ArtifactName: docs
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index a77322f83acbd..42ad0c9f06e23 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -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
@@ -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::
- >>> 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,
More information about the Python-checkins
mailing list