Ability to disable overloaded function signatures being presented when `autodoc_typehints` is `"signature"` or `"both"`

[AbstractUmbra]

Is your feature request related to a problem? Please describe. When the setting above is present and enabled, the build documentation presents multiple entries for ov erloaded function signature:

Describe the solution you'd like As discussed in #10305 I would like to request a setting to override within conf.py to disable this functionality only.

Describe alternatives you've considered Due to the overloaded signatures being rather important, I am unsure if it would be possible to perhaps "collapse" these and only show one signature, but have a button/link present in the built documentation to reveal the overloaded signatures. Otherwise perhaps it can

Additional context N/A but can present anything if you need.

[mbraakhekke]

I fully support this request. I prefer to explain the different usages of overloaded functions but show only the signature of the actual function (with a "universal" signature). Listing all individual overloads can really hurt the readability, IMO. At the risk of being greedy: it would be great if this could be controlled at the level of individual functions/methods.

Is there a workaround possible, currently? I tried to see if I could achieve this with the autodoc-skip-member event but it's emitted only once, not for each individual overload.

Minor point: the overloaded signatures are also shown if autodoc_typehints = "description".

[stinodego]

I would love to have this as an option.

The docs can become unreadable quickly if you have any mildly complex overloading going on. For example, this is the read_excel functionality of Polars: https://pola-rs.github.io/polars/docs/python/dev/reference/api/polars.read_excel.html

[picnixz]

It shouldn't be that hard to do with a configuration value. What we do is redocumenting all possible signatures so we could simply skip this step.

Controlling something at the level of the function should be done via :meta:. The next feature I am working towards to is to implement arbitrary meta "processors". The idea is that you can hack into the directive being executed by injecting some extra content using this meta field. When using autodoc the content would be injected into the directive and you would have a fine control of the autodoc directive.

But this would require a complete refactorisation of autodoc (which IMHO should be done because it's really hard to extend existing implementations).

---

A note for the future me: the code responsible for detecting overloaded functions is the ModuleAnalyzer IIRC. It's one of the component that needs to be improved one day in order to also detect imports correctly and also to be able to subclass it correctly in extensions (currently its implementation is tightly coupled with autodoc and it becomes a pain for extensions that want to improvr it).

At one point I want to collect every autodoc issues because there arr many that are the same or have the same cause.

As a matter of fact, since Python 3.11 or 12, overloaded functions are known at runtime (which is not the case prior to that since the overload decorator acted as a pure identity function).