From 18cc082b0c10da5c27c0ee2f553f3ce87f013bc0 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Mon, 17 Nov 2025 22:50:31 +0100 Subject: [PATCH 1/3] Cover undocummented Pep695 aliases --- tests/roots/test-ext-autodoc/target/pep695.py | 2 ++ tests/test_ext_autodoc/test_ext_autodoc.py | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/tests/roots/test-ext-autodoc/target/pep695.py b/tests/roots/test-ext-autodoc/target/pep695.py index 8aa30aaaaba..bd8a0694882 100644 --- a/tests/roots/test-ext-autodoc/target/pep695.py +++ b/tests/roots/test-ext-autodoc/target/pep695.py @@ -22,6 +22,8 @@ class Foo: type Pep695Alias = Foo """This is PEP695 type alias.""" +type Pep695AliasUndoced = Foo + TypeAliasTypeExplicit = TypeAliasType('TypeAliasTypeExplicit', Foo) # NoQA: UP040 """This is an explicitly constructed typing.TypeAlias.""" diff --git a/tests/test_ext_autodoc/test_ext_autodoc.py b/tests/test_ext_autodoc/test_ext_autodoc.py index 03355d1f703..2919a008618 100644 --- a/tests/test_ext_autodoc/test_ext_autodoc.py +++ b/tests/test_ext_autodoc/test_ext_autodoc.py @@ -2292,6 +2292,12 @@ def test_autodoc_pep695_type_alias() -> None: ' This is PEP695 type alias of PEP695 alias.', '', '', + # Undocumented alias should not inherit any documentations + '.. py:type:: Pep695AliasUndoced', + ' :module: target.pep695', + ' :canonical: ~target.pep695.Foo', + '', + '', '.. py:type:: Pep695AliasUnion', ' :module: target.pep695', ' :canonical: str | int', From daace2a95f34d741d31b99424de2e2e0eaae3bbe Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Tue, 18 Nov 2025 09:49:18 +0100 Subject: [PATCH 2/3] Handle type annotation the same attribute Signed-off-by: Cristian Le --- sphinx/ext/autodoc/_docstrings.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/autodoc/_docstrings.py b/sphinx/ext/autodoc/_docstrings.py index a1b1c84fd64..52d460dd0f7 100644 --- a/sphinx/ext/autodoc/_docstrings.py +++ b/sphinx/ext/autodoc/_docstrings.py @@ -244,7 +244,7 @@ def _get_docstring_lines( return [] return [prepare_docstring(docstring, tab_width)] - if props.obj_type == 'attribute': + if props.obj_type in {'attribute', 'type'}: # Check the attribute has a docstring-comment comment = _get_attribute_comment( parent=parent, obj_path=props.parts, attrname=props.parts[-1] From fb56f11af2df1e301188ad298910dbeab7d57d69 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Tue, 25 Nov 2025 00:51:22 +0000 Subject: [PATCH 3/3] Split from attribute logic --- sphinx/ext/autodoc/_docstrings.py | 18 ++++++++++++++++-- tests/roots/test-ext-autodoc/target/pep695.py | 2 +- tests/test_ext_autodoc/test_ext_autodoc.py | 4 ++-- 3 files changed, 19 insertions(+), 5 deletions(-) diff --git a/sphinx/ext/autodoc/_docstrings.py b/sphinx/ext/autodoc/_docstrings.py index 52d460dd0f7..a1b924dd43a 100644 --- a/sphinx/ext/autodoc/_docstrings.py +++ b/sphinx/ext/autodoc/_docstrings.py @@ -88,7 +88,7 @@ def _prepare_docstrings( ) -> list[list[str]] | None: """Add content from docstrings, attribute documentation and user.""" # add content from attribute documentation - if props.obj_type not in {'data', 'attribute'} and props.parts: + if props.obj_type not in {'data', 'attribute', 'type'} and props.parts: key = ('.'.join(props.parent_names), props.name) try: # make a copy of docstring for attributes to avoid cache @@ -244,7 +244,7 @@ def _get_docstring_lines( return [] return [prepare_docstring(docstring, tab_width)] - if props.obj_type in {'attribute', 'type'}: + if props.obj_type == 'attribute': # Check the attribute has a docstring-comment comment = _get_attribute_comment( parent=parent, obj_path=props.parts, attrname=props.parts[-1] @@ -298,6 +298,20 @@ def _get_docstring_lines( return [] return [prepare_docstring(docstring, tab_width)] + if props.obj_type == 'type': + try: + analyzer = ModuleAnalyzer.for_module(props.module_name) + analyzer.analyze() + except PycodeError: + return None + + key = ('', props.name) + if key in analyzer.attr_docs: + if comment := list(analyzer.attr_docs[key]): + return [comment] + + return None + docstring = getdoc( obj, allow_inherited=inherit_docstrings, diff --git a/tests/roots/test-ext-autodoc/target/pep695.py b/tests/roots/test-ext-autodoc/target/pep695.py index bd8a0694882..3e57ed4baf4 100644 --- a/tests/roots/test-ext-autodoc/target/pep695.py +++ b/tests/roots/test-ext-autodoc/target/pep695.py @@ -22,7 +22,7 @@ class Foo: type Pep695Alias = Foo """This is PEP695 type alias.""" -type Pep695AliasUndoced = Foo +type Pep695AliasUndocumented = Foo TypeAliasTypeExplicit = TypeAliasType('TypeAliasTypeExplicit', Foo) # NoQA: UP040 """This is an explicitly constructed typing.TypeAlias.""" diff --git a/tests/test_ext_autodoc/test_ext_autodoc.py b/tests/test_ext_autodoc/test_ext_autodoc.py index 2919a008618..1d037288038 100644 --- a/tests/test_ext_autodoc/test_ext_autodoc.py +++ b/tests/test_ext_autodoc/test_ext_autodoc.py @@ -2292,8 +2292,8 @@ def test_autodoc_pep695_type_alias() -> None: ' This is PEP695 type alias of PEP695 alias.', '', '', - # Undocumented alias should not inherit any documentations - '.. py:type:: Pep695AliasUndoced', + # Undocumented alias should not inherit any documentation + '.. py:type:: Pep695AliasUndocumented', ' :module: target.pep695', ' :canonical: ~target.pep695.Foo', '',