Doesn't interact correctly with typing.overload.

[hoodmane]

If you provide a @typing.overload for a function, the output is not correct. As far as I can tell, this problem is not fixable without changes to autodoc.

The is that in the presence of a typing.overload, autodoc will never emit an 'autodoc-process-signature' event. You can see the logic here in FunctionDocumenter.format_signature:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py?plain=1#L2193
If self.analyzer.overloads has overloads for this function, it uses overloaded signatures, otherwise it calls super().format_signature. In this case super().format_signature is Documenter.format_signature which actually emits the `'autodoc-process-signature' event:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py?plain=1#L513\

So when overloads exist, we fail to override default behavior. An easy fix for this is:

from sphinx.ext.autodoc import FunctionDocumenter
del FunctionDocumenter.format_signature

Example module

from typing import overload


@overload
def f(a : int, b : int) -> None:
    ...

@overload
def f(a : str, b : str) -> None:
    ...

def f(a : int | str, b : int | str) -> None:
    """
    f does the thing. The arguments can either be ints or strings but they must
    both have the same type.

    Parameters
    ----------
    a:
        The first thing
    b:
        The second thing
    """

Actual output

Actual output

Desired output

achieved with del FunctionDocumenter.format_signature

Desired output

[hoodmane]

I guess you also have to del MethodDocumenter.format_signature.

[gaborbernat]

PR trying to address this is welcome 🤗

[hoodmane]

Are you okay with adding:

from sphinx.ext.autodoc import FunctionDocumenter, MethodDocumenter

del FunctionDocumenter.format_signature
del MethodDocumenter.format_signature

to setup?

[gaborbernat]

I'm willing to try.

[hoodmane]

Okay, PR incoming.

[hoodmane]

Closed by #297.