Merge branch 'master' into refactor_type_annotation2

CHANGES

@@ -72,6 +72,8 @@ Features added
   when the class has two different names; a canonical name and an alias name
 * #8539: autodoc: Add :confval:`autodoc_typehints_description_target` to control
   the behavior of ``autodoc_typehints=description``
+* #8841: autodoc: :confval:`autodoc_docstring_signature` will continue to look
+  for multiple signature lines without backslash character
 * #7549: autosummary: Enable :confval:`autosummary_generate` by default
 * #4826: py domain: Add ``:canonical:`` option to python directives to describe
   the location where the object is defined

doc/usage/extensions/autodoc.rst

@@ -529,15 +529,19 @@ There are also config values that you can set:
    looks like a signature, use the line as the signature and remove it from the
    docstring content.
 
-   If the signature line ends with backslash, autodoc considers the function has
-   multiple signatures and look at the next line of the docstring.  It is useful
-   for overloaded function.
+   autodoc will continue to look for multiple signature lines,
+   stopping at the first line that does not look like a signature.
+   This is useful for declaring overloaded function signatures.
 
    .. versionadded:: 1.1
    .. versionchanged:: 3.1
 
       Support overloaded signatures
 
+   .. versionchanged:: 4.0
+
+      Overloaded signatures do not need to be separated by a backslash
+
 .. confval:: autodoc_mock_imports
 
    This value contains a list of modules to be mocked up. This is useful when

sphinx/ext/autodoc/__init__.py

@@ -1191,20 +1191,17 @@ class DocstringSignatureMixin:
                     break
 
                 if line.endswith('\\'):
-                    multiline = True
                     line = line.rstrip('\\').rstrip()
-                else:
-                    multiline = False
 
                 # match first line of docstring against signature RE
                 match = py_ext_sig_re.match(line)
                 if not match:
-                    continue
+                    break
                 exmod, path, base, args, retann = match.groups()
 
                 # the base name must match ours
                 if base not in valid_names:
-                    continue
+                    break
 
                 # re-prepare docstring to ignore more leading indentation
                 tab_width = self.directive.state.document.settings.tab_width  # type: ignore
@@ -1218,13 +1215,6 @@ class DocstringSignatureMixin:
                     # subsequent signatures
                     self._signatures.append("(%s) -> %s" % (args, retann))
 
-                if multiline:
-                    # the signature have multiple signatures on docstring
-                    continue
-                else:
-                    # don't look any further
-                    break
-
             if result:
                 # finish the loop when signature found
                 break

sphinx/util/docfields.py

@@ -15,11 +15,11 @@ from docutils import nodes
 from docutils.nodes import Node
 
 from sphinx import addnodes
+from sphinx.environment import BuildEnvironment
 from sphinx.util.typing import TextlikeNode
 
 if TYPE_CHECKING:
     from sphinx.directive import ObjectDescription
-    from sphinx.environment import BuildEnvironment
 
 
 def _is_single_paragraph(node: nodes.field_body) -> bool:
@@ -62,7 +62,7 @@ class Field:
 
     def make_xref(self, rolename: str, domain: str, target: str,
                   innernode: Type[TextlikeNode] = addnodes.literal_emphasis,
-                  contnode: Node = None, env: "BuildEnvironment" = None) -> Node:
+                  contnode: Node = None, env: BuildEnvironment = None) -> Node:
         if not rolename:
             return contnode or innernode(target, target)
         refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
@@ -74,14 +74,14 @@ class Field:
 
     def make_xrefs(self, rolename: str, domain: str, target: str,
                    innernode: Type[TextlikeNode] = addnodes.literal_emphasis,
-                   contnode: Node = None, env: "BuildEnvironment" = None) -> List[Node]:
+                   contnode: Node = None, env: BuildEnvironment = None) -> List[Node]:
         return [self.make_xref(rolename, domain, target, innernode, contnode, env)]
 
     def make_entry(self, fieldarg: str, content: List[Node]) -> Tuple[str, List[Node]]:
         return (fieldarg, content)
 
     def make_field(self, types: Dict[str, List[Node]], domain: str,
-                   item: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
+                   item: Tuple, env: BuildEnvironment = None) -> nodes.field:
         fieldarg, content = item
         fieldname = nodes.field_name('', self.label)
         if fieldarg:
@@ -121,7 +121,7 @@ class GroupedField(Field):
         self.can_collapse = can_collapse
 
     def make_field(self, types: Dict[str, List[Node]], domain: str,
-                   items: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
+                   items: Tuple, env: BuildEnvironment = None) -> nodes.field:
         fieldname = nodes.field_name('', self.label)
         listnode = self.list_type()
         for fieldarg, content in items:
@@ -170,7 +170,7 @@ class TypedField(GroupedField):
         self.typerolename = typerolename
 
     def make_field(self, types: Dict[str, List[Node]], domain: str,
-                   items: Tuple, env: "BuildEnvironment" = None) -> nodes.field:
+                   items: Tuple, env: BuildEnvironment = None) -> nodes.field:
         def handle_item(fieldarg: str, content: str) -> nodes.paragraph:
             par = nodes.paragraph()
             par.extend(self.make_xrefs(self.rolename, domain, fieldarg,

tests/roots/test-ext-autodoc/target/docstring_signature.py

@@ -23,3 +23,9 @@ class E:
     def __init__(self):
         """E(foo: int, bar: int, baz: int) -> None \\
         E(foo: str, bar: str, baz: str) -> None"""
+
+
+class F:
+    def __init__(self):
+        """F(foo: int, bar: int, baz: int) -> None
+        F(foo: str, bar: str, baz: str) -> None"""

tests/test_ext_autodoc_configs.py

@@ -348,7 +348,11 @@ def test_autoclass_content_and_docstring_signature_class(app):
         '',
         '.. py:class:: E()',
         '   :module: target.docstring_signature',
-        ''
+        '',
+        '',
+        '.. py:class:: F()',
+        '   :module: target.docstring_signature',
+        '',
     ]
 
 
@@ -382,7 +386,12 @@ def test_autoclass_content_and_docstring_signature_init(app):
         '.. py:class:: E(foo: int, bar: int, baz: int) -> None',
         '              E(foo: str, bar: str, baz: str) -> None',
         '   :module: target.docstring_signature',
-        ''
+        '',
+        '',
+        '.. py:class:: F(foo: int, bar: int, baz: int) -> None',
+        '              F(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
+        '',
     ]
 
 
@@ -421,6 +430,11 @@ def test_autoclass_content_and_docstring_signature_both(app):
         '              E(foo: str, bar: str, baz: str) -> None',
         '   :module: target.docstring_signature',
         '',
+        '',
+        '.. py:class:: F(foo: int, bar: int, baz: int) -> None',
+        '              F(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
+        '',
     ]