bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282)

Author: JulienPalard

.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') }}:

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

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.
 

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`.

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*.

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,

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

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

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

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`.