Stubgen can read multiple escaped signatures at the start of a docstring

[AWhetter]

Description

The autodoc extension for Sphinx supports using multiple function signatures defined at the start of the docstring on multiple lines separated by a backslash (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_docstring_signature).
For example:

"""example(arg0: int) -> int \
example(arg0: str) -> str
This is the summary line.

This is the rest of the docstring.
"""

Currently stubgen fails to parse these lines, which results in it outputting the following signature for the above example: def example(*args, **kwargs) -> Any.

This change allows stubgen to parse these leading signatures in a docstring. I've done so in a backwards compatible way, but I have made what I think is a compromise to make it backwards compatible. I think that ideally any leading signatures in a docstring should be the only signatures that stubgen reads from a docstring.
I've made the change such that even if there are leading signatures in the docstring, the remaining signatures are still read. This is compatible with the current format that pybind11 outputs docstrings with. However I am currently looking to make pybind support this same docstring format that Sphinx expects (pybind/pybind11#2621).

So the current situation, before my changes, is:

# pybind11 output
"""example(*args, **kwargs) -> Any
Overloaded function.

1. example(arg0: int) -> int

2. example(arg0: str) -> str
"""

# stubgen outputs from the above docstring
"""
from typing import overload
@overload
def example(arg0: int) -> int: ...

@overload
def example(arg0: str) -> str: ...

@overload
def example(*args, **kwargs) -> Any: ...
"""

If only the pybind11 change goes ahead (no stubgen changes required because it cannot parse the leading signatures but can parse the section headings):

# pybind11 output
"""example(arg0: int) -> int \
example(arg0: str) -> str
Overloaded function.

1. example(arg0: int) -> int

2. example(arg0: str) -> str
"""

# stubgen outputs from the above docstring
"""
from typing import overload
@overload
def example(arg0: int) -> int: ...

@overload
def example(arg0: str) -> str: ...
"""

The change that I've made in this pull request allows for the extra flexibility of not needing the sections in the docstring:

# pybind11 output
"""example(arg0: int) -> int \
example(arg0: str) -> str
Overloaded function.

This bit of the docstring does not need to include signatures.
"""

# stubgen outputs from the above docstring
"""
from typing import overload
@overload
def example(arg0: int) -> int: ...

@overload
def example(arg0: str) -> str: ...
"""

What I think the ideal situation is:

# pybind11 output
"""example(arg0: int) -> int \
example(arg0: str) -> str
Overloaded function.

example(arg0: float) -> float
Although this is an unusual case, this extra signature should not get parsed.
"""

# stubgen outputs from the above docstring
"""
from typing import overload
@overload
def example(arg0: int) -> int: ...

@overload
def example(arg0: str) -> str: ...
"""

Test Plan

A test has been included. It failed before making changes to mypy.

[AWhetter]

From Sphinx v4, Sphinx will no long required signatures to be separated by a backslash. Therefore this change is not required either.