diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 5ee71c782..1bfa8086c 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 57499ec6f..5a0a8ca10 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/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 diff --git a/tests/roots/test-ext-autodoc/target/docstring_signature.py b/tests/roots/test-ext-autodoc/target/docstring_signature.py index 244109629..d9deb6244 100644 --- a/tests/roots/test-ext-autodoc/target/docstring_signature.py +++ b/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""" diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py index 9477e3f95..bc8c01fbd 100644 --- a/tests/test_ext_autodoc_configs.py +++ b/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', + '', ]