Merge pull request #10353 from tk0miya/10305_optional_forwardref_annotations

Fix #10305: autodoc: Failed to extract optional forwardrefs

CHANGES

@@ -85,6 +85,8 @@ Bugs fixed
   mixture of keyword only arguments with/without defaults
 * #10310: autodoc: class methods are not documented when decorated with mocked
   function
+* #10305: autodoc: Failed to extract optional forward-ref'ed typehints correctly
+  via :confval:`autodoc_type_aliases`
 * #10214: html: invalid language tag was generated if :confval:`language`
   contains a country code (ex. zh_CN)
 * #10236: html search: objects are duplicated in search result

sphinx/util/inspect.py

@@ -487,6 +487,12 @@ class TypeAliasForwardRef:
     def __eq__(self, other: Any) -> bool:
         return self.name == other
 
+    def __hash__(self) -> int:
+        return hash(self.name)
+
+    def __repr__(self) -> str:
+        return self.name
+
 
 class TypeAliasModule:
     """Pseudo module class for autodoc_type_aliases."""

tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import io
-from typing import overload
+from typing import Optional, overload
 
 myint = int
 
@@ -11,6 +11,9 @@ variable: myint
 #: docstring
 variable2 = None  # type: myint
 
+#: docstring
+variable3: Optional[myint]
+
 
 def read(r: io.BytesIO) -> io.StringIO:
     """docstring"""

tests/test_ext_autodoc_configs.py

@@ -1150,6 +1150,13 @@ def test_autodoc_type_aliases(app):
         '',
         '   docstring',
         '',
+        '',
+        '.. py:data:: variable3',
+        '   :module: target.autodoc_type_aliases',
+        '   :type: Optional[int]',
+        '',
+        '   docstring',
+        '',
     ]
 
     # define aliases
@@ -1214,6 +1221,13 @@ def test_autodoc_type_aliases(app):
         '',
         '   docstring',
         '',
+        '',
+        '.. py:data:: variable3',
+        '   :module: target.autodoc_type_aliases',
+        '   :type: Optional[myint]',
+        '',
+        '   docstring',
+        '',
     ]
 
 

tests/test_util_inspect.py

@@ -7,11 +7,21 @@ import functools
 import sys
 import types
 from inspect import Parameter
+from typing import Optional
 
 import pytest
 
 from sphinx.util import inspect
-from sphinx.util.inspect import TypeAliasNamespace, stringify_signature
+from sphinx.util.inspect import TypeAliasForwardRef, TypeAliasNamespace, stringify_signature
+from sphinx.util.typing import stringify
+
+
+def test_TypeAliasForwardRef():
+    alias = TypeAliasForwardRef('example')
+    assert stringify(alias) == 'example'
+
+    alias = Optional[alias]
+    assert stringify(alias) == 'Optional[example]'
 
 
 def test_TypeAliasNamespace():