IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

copy solution to method documenter

Browse Source
This commit is contained in:
Barak A Katzir 2025-02-13 20:51:00 +02:00
parent d7df3de400
commit 9f45a5c673
No known key found for this signature in database
GPG Key ID: E4D7B62ACDD24441
3 changed files with 62 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
sphinx/ext/autodoc/__init__.py
View File

@ -1502,12 +1502,8 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
sig = self.merge_default_value(self.overload_impl_sig, sig)
args = stringify_signature(sig, **kwargs)
except TypeError as exc:
overload = '' if self.overload_impl_sig is None else 'overload '
logger.warning(
__('Failed to get a %sfunction signature for %s: %s'),
overload,
self.fullname,
exc,
__('Failed to get a function signature for %s: %s'), self.fullname, exc
)
return ''
except ValueError:
@ -2395,6 +2391,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
directivetype = 'method'
member_order = 50
priority = 1 # must be more than FunctionDocumenter
overload_impl_sig: Signature | None = None
@classmethod
def can_document_member(
@ -2454,6 +2451,8 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
bound_method=True,
type_aliases=self.config.autodoc_type_aliases,
)
if self.overload_impl_sig is not None:
sig = self.merge_default_value(self.overload_impl_sig, sig)
args = stringify_signature(sig, **kwargs)
except TypeError as exc:
logger.warning(
@ -2542,20 +2541,15 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
type_aliases=self.config.autodoc_type_aliases,
)
__globals__ = safe_getattr(self.object, '__globals__', {})
for overload in self.analyzer.overloads['.'.join(self.objpath)]:
overload = self.merge_default_value(actual, overload)
overload = evaluate_signature(
overload, __globals__, self.config.autodoc_type_aliases
)
if not inspect.isstaticmethod(
self.object, cls=self.parent, name=self.object_name
):
parameters = list(overload.parameters.values())
overload = overload.replace(parameters=parameters[1:])
sig = stringify_signature(overload, **kwargs)
sigs.append(sig)
overload_kwargs = kwargs | {'show_annotation': True}
for overload_func in get_overloads(self.object):
documenter = type(self)(self.directive, '')
documenter.object = overload_func
documenter.objpath = ['']
documenter.parent = self.parent
# pass actual implementation signature to merge default values later
documenter.overload_impl_sig = actual
sigs.append(documenter.format_signature(**overload_kwargs))
return '\n'.join(sigs)
@ -2564,7 +2558,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
parameters = list(overload.parameters.values())
for i, param in enumerate(parameters):
actual_param = actual.parameters.get(param.name)
if actual_param and param.default == '...':
if actual_param and param.default in {'...', Ellipsis}:
parameters[i] = param.replace(default=actual_param.default)
return overload.replace(parameters=parameters)

20
tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py
View File

@ -51,6 +51,26 @@ class Foo:
def __init__(self):
self.attr2: myint = None #: docstring
def method1(self, x: Union[frac.Fraction, myfrac]) -> Union[frac.Fraction, myfrac]: # NoQA: UP007
"""docstring"""
return self.attr1 * x
@overload
def method2(self, x: frac.Fraction) -> frac.Fraction: ...
@overload
def method2(self, x: myfrac) -> myfrac: ...
@overload
def method2(
self,
x: Union[frac.Fraction, myfrac], # NoQA: UP007
) -> Union[frac.Fraction, myfrac]: ... # NoQA: UP007
def method2(self, x):
"""docstring"""
return self.attr2 * x
@overload
def prod(x: tuple[float, myfrac]) -> float: ...

28
tests/test_extensions/test_ext_autodoc_configs.py
View File

@ -1367,6 +1367,20 @@ def test_autodoc_type_aliases(app):
' docstring',
'',
'',
' .. py:method:: Foo.method1(x: ~fractions.Fraction | float) -> ~fractions.Fraction | float',
' :module: target.autodoc_type_aliases',
'',
' docstring',
'',
'',
' .. py:method:: Foo.method2(x: ~fractions.Fraction) -> ~fractions.Fraction',
' Foo.method2(x: float) -> float',
' Foo.method2(x: ~fractions.Fraction | float) -> ~fractions.Fraction | float',
' :module: target.autodoc_type_aliases',
'',
' docstring',
'',
'',
'.. py:function:: mult(x: int, y: int) -> int',
' mult(x: float, y: float) -> float',
' :module: target.autodoc_type_aliases',
@ -1454,6 +1468,20 @@ def test_autodoc_type_aliases(app):
' docstring',
'',
'',
" .. py:method:: Foo.method1(x: ~fractions.Fraction | TypeAliasForwardRef('my.module.myfrac')) -> ~fractions.Fraction | TypeAliasForwardRef('my.module.myfrac')",
' :module: target.autodoc_type_aliases',
'',
' docstring',
'',
'',
' .. py:method:: Foo.method2(x: ~fractions.Fraction) -> ~fractions.Fraction',
' Foo.method2(x: my.module.myfrac) -> my.module.myfrac',
" Foo.method2(x: ~fractions.Fraction | TypeAliasForwardRef('my.module.myfrac')) -> ~fractions.Fraction | TypeAliasForwardRef('my.module.myfrac')",
' :module: target.autodoc_type_aliases',
'',
' docstring',
'',
'',
'.. py:function:: mult(x: int, y: int) -> int',
' mult(x: my.module.myfrac, y: my.module.myfrac) -> my.module.myfrac',
' :module: target.autodoc_type_aliases',