[Python-checkins] bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282)
JulienPalard
webhook-mailer at python.org
Mon Jan 25 09:46:18 EST 2021
https://github.com/python/cpython/commit/5c1f15b4b1024cbf0acc85832f0c623d1a4605fd
commit: 5c1f15b4b1024cbf0acc85832f0c623d1a4605fd
branch: master
author: Julien Palard <julien at palard.fr>
committer: JulienPalard <julien at palard.fr>
date: 2021-01-25T15:46:06+01:00
summary:
bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282)
files:
M .azure-pipelines/docs-steps.yml
M Doc/conf.py
M Doc/library/asyncio-stream.rst
M Doc/library/base64.rst
M Doc/library/difflib.rst
M Doc/library/doctest.rst
M Doc/library/email.header.rst
M Doc/library/functions.rst
M Doc/library/http.cookies.rst
M Doc/library/io.rst
M Doc/library/xml.dom.minidom.rst
diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml
index 8e72baf2b12fe..33d379b95aa3d 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==3.2.1 blurb python-docs-theme
+- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
displayName: 'Install build dependencies'
- ${{ if ne(parameters.latex, 'true') }}:
diff --git a/Doc/conf.py b/Doc/conf.py
index 6b88c23a44473..cf250981f5875 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -237,3 +237,5 @@
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
# documentation is built with -W (warnings treated as errors).
c_warn_on_allowed_pre_v3 = False
+
+strip_signature_backslash = True
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 9b456c14351e4..ad3c7442ad56c 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -185,7 +185,7 @@ StreamReader
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
- .. coroutinemethod:: readuntil(separator=b'\n')
+ .. coroutinemethod:: readuntil(separator=b'\\n')
Read data from the stream until *separator* is found.
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 25b3a4ca2967c..2f24bb63912fb 100644
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -199,7 +199,7 @@ The modern interface provides:
.. versionadded:: 3.4
-.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
+.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
return the decoded :class:`bytes`.
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index a5ee0fb538979..aa08988c8b36f 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -149,7 +149,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
contains a good example of its use.
-.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
+.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in context diff format.
@@ -279,7 +279,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
emu
-.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
+.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in unified diff format.
@@ -321,7 +321,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
See :ref:`difflib-interface` for a more detailed example.
-.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')
+.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\\n')
Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a
sequence of delta lines (also bytes) in the format returned by *dfunc*.
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 42ad0c9f06e23..a77322f83acbd 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -719,51 +719,36 @@ 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::
-.. doctest::
- :no-trim-doctest-flags:
-
- >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
+ >>> 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:
-
-.. doctest::
- :no-trim-doctest-flags:
+so::
- >>> 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::
-.. doctest::
- :no-trim-doctest-flags:
-
- >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+ >>> 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:
-
-.. doctest::
- :no-trim-doctest-flags:
+combined::
- >>> 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:
-
-.. doctest::
- :no-trim-doctest-flags:
+a directive to comfortably fit on the same line::
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
@@ -808,23 +793,18 @@ 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
-
-.. doctest::
+Another bad idea is to print things that embed an object address, like ::
- >>> id(1.0) # certain to fail some of the time # doctest: +SKIP
+ >>> id(1.0) # certain to fail some of the time
7948648
>>> class C: pass
- >>> 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:
+ >>> C() # the default repr() for instances embeds an address
+ <__main__.C instance at 0x00AC18F0>
-.. doctest::
- :no-trim-doctest-flags:
+The :const:`ELLIPSIS` directive gives a nice approach for the last example::
- >>> C() # doctest: +ELLIPSIS
- <C object at 0x...>
+ >>> C() #doctest: +ELLIPSIS
+ <__main__.C instance 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,
diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
index e093f138936b3..07152c224f2ff 100644
--- a/Doc/library/email.header.rst
+++ b/Doc/library/email.header.rst
@@ -116,7 +116,7 @@ Here is the :class:`Header` class description:
if *s* is a byte string.
- .. method:: encode(splitchars=';, \t', maxlinelen=None, linesep='\n')
+ .. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
Encode a message header into an RFC-compliant format, possibly wrapping
long lines and encapsulating non-ASCII parts in base64 or quoted-printable
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index f28d63b6b3d21..f84353ce391d1 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1334,7 +1334,7 @@ are always available. They are listed here in alphabetical order.
supported.
-.. function:: print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
+.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
Print *objects* to the text stream *file*, separated by *sep* and followed
by *end*. *sep*, *end*, *file* and *flush*, if present, must be given as keyword
diff --git a/Doc/library/http.cookies.rst b/Doc/library/http.cookies.rst
index a2c1eb00d8b33..17792b200599b 100644
--- a/Doc/library/http.cookies.rst
+++ b/Doc/library/http.cookies.rst
@@ -93,7 +93,7 @@ Cookie Objects
:meth:`value_decode` are inverses on the range of *value_decode*.
-.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')
+.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\\r\\n')
Return a string representation suitable to be sent as HTTP headers. *attrs* and
*header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 048cb2a7ff692..aecbec56866d7 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -964,7 +964,7 @@ Text I/O
.. versionadded:: 3.7
-.. class:: StringIO(initial_value='', newline='\n')
+.. class:: StringIO(initial_value='', newline='\\n')
A text stream using an in-memory text buffer. It inherits
:class:`TextIOBase`.
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index e1cc96794221a..bf72c46561b7c 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -174,7 +174,7 @@ module documentation. This section lists the differences between the API and
The :meth:`toxml` method now preserves the attribute order specified
by the user.
-.. method:: Node.toprettyxml(indent="\t", newl="\n", encoding=None, \
+.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None, \
standalone=None)
Return a pretty-printed version of the document. *indent* specifies the
More information about the Python-checkins
mailing list