From 5c1f15b4b1024cbf0acc85832f0c623d1a4605fd Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 25 Jan 2021 15:46:06 +0100 Subject: [PATCH] bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282) --- .azure-pipelines/docs-steps.yml | 2 +- Doc/conf.py | 2 ++ Doc/library/asyncio-stream.rst | 2 +- Doc/library/base64.rst | 2 +- Doc/library/difflib.rst | 6 ++-- Doc/library/doctest.rst | 54 +++++++++++---------------------- Doc/library/email.header.rst | 2 +- Doc/library/functions.rst | 2 +- Doc/library/http.cookies.rst | 2 +- Doc/library/io.rst | 2 +- Doc/library/xml.dom.minidom.rst | 2 +- 11 files changed, 30 insertions(+), 48 deletions(-) diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml index 8e72baf2b12fe1..33d379b95aa3dc 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 6b88c23a44473f..cf250981f58752 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 9b456c14351e44..ad3c7442ad56cd 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 25b3a4ca2967cb..2f24bb63912fb6 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 a5ee0fb5389793..aa08988c8b36f7 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 42ad0c9f06e237..a77322f83acbde 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 - - -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() #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 e093f138936b36..07152c224f2ff0 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 f28d63b6b3d21a..f84353ce391d14 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 a2c1eb00d8b33d..17792b200599bd 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 048cb2a7ff6924..aecbec56866d73 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 e1cc96794221ad..bf72c46561b7c7 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