mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #10147 from zuqq/4.x
Apply `autodoc_typehints_format` to all type hints
This commit is contained in:
Takeshi KOMIYA
GitHub
commit
19c347e790
2
CHANGES
2
CHANGES
@ -70,6 +70,8 @@ Features added
|
||||
* #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
|
||||
include undocumented return values but not undocumented parameters.
|
||||
* #10285: autodoc: singledispatch functions having typehints are not documented
|
||||
* autodoc: :confval:`autodoc_typehints_format` now also applies to attributes,
|
||||
data, properties, and type variable bounds.
|
||||
* #10258: autosummary: Recognize a documented attribute of a module as
|
||||
non-imported
|
||||
* #10028: Removed internal usages of JavaScript frameworks (jQuery and
|
||||
|
||||
@ -1897,7 +1897,10 @@ class TypeVarMixin(DataDocumenterMixinBase):
|
||||
if isinstance(self.object, TypeVar):
|
||||
attrs = [repr(self.object.__name__)]
|
||||
for constraint in self.object.__constraints__:
|
||||
attrs.append(stringify_typehint(constraint))
|
||||
if self.config.autodoc_typehints_format == "short":
|
||||
attrs.append(stringify_typehint(constraint, "smart"))
|
||||
else:
|
||||
attrs.append(stringify_typehint(constraint))
|
||||
if self.object.__bound__:
|
||||
if self.config.autodoc_typehints_format == "short":
|
||||
bound = restify(self.object.__bound__, "smart")
|
||||
@ -2019,7 +2022,11 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
|
||||
annotations = get_type_hints(self.parent, None,
|
||||
self.config.autodoc_type_aliases)
|
||||
if self.objpath[-1] in annotations:
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
|
||||
if self.config.autodoc_typehints_format == "short":
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]),
|
||||
"smart")
|
||||
else:
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
|
||||
self.add_line(' :type: ' + objrepr, sourcename)
|
||||
|
||||
try:
|
||||
@ -2619,7 +2626,11 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
|
||||
annotations = get_type_hints(self.parent, None,
|
||||
self.config.autodoc_type_aliases)
|
||||
if self.objpath[-1] in annotations:
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
|
||||
if self.config.autodoc_typehints_format == "short":
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]),
|
||||
"smart")
|
||||
else:
|
||||
objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
|
||||
self.add_line(' :type: ' + objrepr, sourcename)
|
||||
|
||||
try:
|
||||
@ -2743,7 +2754,10 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): #
|
||||
signature = inspect.signature(func,
|
||||
type_aliases=self.config.autodoc_type_aliases)
|
||||
if signature.return_annotation is not Parameter.empty:
|
||||
objrepr = stringify_typehint(signature.return_annotation)
|
||||
if self.config.autodoc_typehints_format == "short":
|
||||
objrepr = stringify_typehint(signature.return_annotation, "smart")
|
||||
else:
|
||||
objrepr = stringify_typehint(signature.return_annotation)
|
||||
self.add_line(' :type: ' + objrepr, sourcename)
|
||||
except TypeError as exc:
|
||||
logger.warning(__("Failed to get a function signature for %s: %s"),
|
||||
|
||||
@ -1,7 +1,13 @@
|
||||
from typing import Any, Tuple, Union
|
||||
import pathlib
|
||||
from typing import Any, Tuple, TypeVar, Union
|
||||
|
||||
CONST1: int
|
||||
#: docstring
|
||||
CONST2: int = 1
|
||||
#: docstring
|
||||
CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
|
||||
#: docstring
|
||||
T = TypeVar("T", bound=pathlib.PurePosixPath)
|
||||
|
||||
|
||||
def incr(a: int, b: int = 1) -> int:
|
||||
@ -16,6 +22,7 @@ def decr(a, b = 1):
|
||||
class Math:
|
||||
CONST1: int
|
||||
CONST2: int = 1
|
||||
CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
|
||||
|
||||
def __init__(self, s: str, o: Any = None) -> None:
|
||||
pass
|
||||
@ -42,6 +49,10 @@ class Math:
|
||||
def prop(self) -> int:
|
||||
return 0
|
||||
|
||||
@property
|
||||
def path(self) -> pathlib.PurePosixPath:
|
||||
return pathlib.PurePosixPath("/a/b/c")
|
||||
|
||||
|
||||
def tuple_args(x: Tuple[int, Union[int, str]]) -> Tuple[int, int]:
|
||||
pass
|
||||
|
||||
@ -613,6 +613,22 @@ def test_autodoc_typehints_signature(app):
|
||||
' :type: int',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST2',
|
||||
' :module: target.typehints',
|
||||
' :type: int',
|
||||
' :value: 1',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST3',
|
||||
' :module: target.typehints',
|
||||
' :type: ~pathlib.PurePosixPath',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Math(s: str, o: %s = None)' % type_o,
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -628,6 +644,12 @@ def test_autodoc_typehints_signature(app):
|
||||
' :value: 1',
|
||||
'',
|
||||
'',
|
||||
' .. py:attribute:: Math.CONST3',
|
||||
' :module: target.typehints',
|
||||
' :type: ~pathlib.PurePosixPath',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
'',
|
||||
' .. py:method:: Math.decr(a: int, b: int = 1) -> int',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -644,6 +666,11 @@ def test_autodoc_typehints_signature(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.path',
|
||||
' :module: target.typehints',
|
||||
' :type: ~pathlib.PurePosixPath',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.prop',
|
||||
' :module: target.typehints',
|
||||
' :type: int',
|
||||
@ -661,6 +688,14 @@ def test_autodoc_typehints_signature(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: T',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
" alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
|
||||
'Union[str, Unknown]] = None, *args: str, **kwargs: str) -> None',
|
||||
' :module: target.typehints',
|
||||
@ -700,6 +735,20 @@ def test_autodoc_typehints_none(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST2',
|
||||
' :module: target.typehints',
|
||||
' :value: 1',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST3',
|
||||
' :module: target.typehints',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Math(s, o=None)',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -713,6 +762,11 @@ def test_autodoc_typehints_none(app):
|
||||
' :value: 1',
|
||||
'',
|
||||
'',
|
||||
' .. py:attribute:: Math.CONST3',
|
||||
' :module: target.typehints',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
'',
|
||||
' .. py:method:: Math.decr(a, b=1)',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -729,6 +783,10 @@ def test_autodoc_typehints_none(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.path',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.prop',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -745,6 +803,14 @@ def test_autodoc_typehints_none(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: T',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
" alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: complex_func(arg1, arg2, arg3=None, *args, **kwargs)',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -1153,7 +1219,7 @@ def test_autodoc_type_aliases(app):
|
||||
'',
|
||||
'.. py:data:: variable3',
|
||||
' :module: target.autodoc_type_aliases',
|
||||
' :type: Optional[int]',
|
||||
' :type: ~typing.Optional[int]',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
@ -1224,7 +1290,7 @@ def test_autodoc_type_aliases(app):
|
||||
'',
|
||||
'.. py:data:: variable3',
|
||||
' :module: target.autodoc_type_aliases',
|
||||
' :type: Optional[myint]',
|
||||
' :type: ~typing.Optional[myint]',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
@ -1274,6 +1340,22 @@ def test_autodoc_typehints_format_fully_qualified(app):
|
||||
' :type: int',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST2',
|
||||
' :module: target.typehints',
|
||||
' :type: int',
|
||||
' :value: 1',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: CONST3',
|
||||
' :module: target.typehints',
|
||||
' :type: pathlib.PurePosixPath',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
'',
|
||||
'.. py:class:: Math(s: str, o: %s = None)' % type_o,
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -1289,6 +1371,12 @@ def test_autodoc_typehints_format_fully_qualified(app):
|
||||
' :value: 1',
|
||||
'',
|
||||
'',
|
||||
' .. py:attribute:: Math.CONST3',
|
||||
' :module: target.typehints',
|
||||
' :type: pathlib.PurePosixPath',
|
||||
" :value: PurePosixPath('/a/b/c')",
|
||||
'',
|
||||
'',
|
||||
' .. py:method:: Math.decr(a: int, b: int = 1) -> int',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
@ -1305,6 +1393,11 @@ def test_autodoc_typehints_format_fully_qualified(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.path',
|
||||
' :module: target.typehints',
|
||||
' :type: pathlib.PurePosixPath',
|
||||
'',
|
||||
'',
|
||||
' .. py:property:: Math.prop',
|
||||
' :module: target.typehints',
|
||||
' :type: int',
|
||||
@ -1322,6 +1415,14 @@ def test_autodoc_typehints_format_fully_qualified(app):
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
'',
|
||||
'.. py:data:: T',
|
||||
' :module: target.typehints',
|
||||
'',
|
||||
' docstring',
|
||||
'',
|
||||
" alias of TypeVar('T', bound=\\ :py:class:`pathlib.PurePosixPath`)",
|
||||
'',
|
||||
'',
|
||||
'.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
|
||||
'Union[str, Unknown]] = None, *args: str, **kwargs: str) -> None',
|
||||
' :module: target.typehints',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user