Describe the bug
the implementation for autodoc.FunctionDocumenter has hardcoded paths for "overloads" which bypass the signature processing hooks and also provide no means of disabling "overloads" without end-user manipulation of internal state.
end result is the formatting or presence of overloads cannot be affected by end users. output for complex libraries like SQLAlchemy is unreadable.
This can be seen in sphinx source here, where the default format_signature that calls the hooks is skipped:
|
if (self.analyzer and |
|
'.'.join(self.objpath) in self.analyzer.overloads and |
|
self.config.autodoc_typehints != 'none'): |
|
# Use signatures for overloaded functions instead of the implementation function. |
|
overloaded = True |
|
else: |
|
overloaded = False |
|
sig = super().format_signature(**kwargs) |
|
sigs.append(sig) |
below is a hardcoded signature rendering for "overload" that calls no hooks:
|
if overloaded: |
|
actual = inspect.signature(self.object, |
|
type_aliases=self.config.autodoc_type_aliases) |
|
__globals__ = safe_getattr(self.object, '__globals__', {}) |
|
for overload in self.analyzer.overloads.get('.'.join(self.objpath)): |
|
overload = self.merge_default_value(actual, overload) |
|
overload = evaluate_signature(overload, __globals__, |
|
self.config.autodoc_type_aliases) |
|
|
|
sig = stringify_signature(overload, **kwargs) |
|
sigs.append(sig) |
|
|
|
return "\n".join(sigs) |
How to Reproduce
def autodoc_before_process_signature(app, obj, bound_method):
print(obj.__qualname__)
def setup(app):
app.connect("autodoc-before-process-signature", autodoc_before_process_signature)methods that have @overload will not be printed.
Expected behavior
hooks are available to affect how signatures are rendered in overload, parameters are provided to disable using overloads when doing autodoc
Your project
https://docs.sqlalchemy.org/en/20/
Screenshots
OS
linux
Python version
3.10
Sphinx version
4.5.0
Sphinx extensions
autodoc
Extra tools
No response
Additional context
No response
Describe the bug
the implementation for autodoc.FunctionDocumenter has hardcoded paths for "overloads" which bypass the signature processing hooks and also provide no means of disabling "overloads" without end-user manipulation of internal state.
end result is the formatting or presence of overloads cannot be affected by end users. output for complex libraries like SQLAlchemy is unreadable.
This can be seen in sphinx source here, where the default format_signature that calls the hooks is skipped:
sphinx/sphinx/ext/autodoc/__init__.py
Lines 1334 to 1342 in c1ee5bc
below is a hardcoded signature rendering for "overload" that calls no hooks:
sphinx/sphinx/ext/autodoc/__init__.py
Lines 1356 to 1368 in c1ee5bc
How to Reproduce
methods that have
@overloadwill not be printed.Expected behavior
hooks are available to affect how signatures are rendered in overload, parameters are provided to disable using overloads when doing autodoc
Your project
https://docs.sqlalchemy.org/en/20/
Screenshots
OS
linux
Python version
3.10
Sphinx version
4.5.0
Sphinx extensions
autodoc
Extra tools
No response
Additional context
No response