Fix sphinx-doc#11410: autodoc: can't detect overloads for functions defined in other file

[akpircher]

Subject: fix autodoc not detecting overloads defined in other module, but exported in this module.

Feature or Bugfix

• Bugfix

Purpose

• Document overloads for a function defined in a private module but exposed publicly.

Detail

This PR fix is based on the solution used in #8283. Currently, the Documenter class gets overloads defined in the same file, and records the real/source module as a dependency, and then nothing else.

The fix provided here adds overloads defined in the "real" module to the public module.

I'm not entirely sure if this is the "right" way to go about this, but it's the simplest solution without a refactor.

Relates

• autodoc can't detect overloads for functions defined in other file #11410

[picnixz]

I'm not entirely sure if this is the "right" way to go about this, but it's the simplest solution without a refactor.

I think it's better if we lookup for the correct target and fetch its ovreloading rather than polluting the analyzer of the module importing an overloaded definition. I would like a larger coverage where:

• The overloaded function is imported but should not be rendered (e.g., you ask to only document things in __all__ but you are not re-exporting the overloaded function): in this case, the analyzer should not be called at all.
• The overloaded function is imported is aliased and should be rendered: render it with the aliased name.
• The overloaded function is imported is aliased and should not be rendered: same as case 1.

By the way, why does the class documenter works (i.e., the overloaded definitions seem to be here for the constructor) but not for functions?