From 9a163dcb58b35f46b806c4addd719ff353b46015 Mon Sep 17 00:00:00 2001
From: Casey Brooks <casey.brooks@agyn.io>
Date: Fri, 26 Dec 2025 17:31:40 +0000
Subject: [PATCH] fix(autodoc): honor aliases in description

---
 sphinx/ext/autodoc/typehints.py                  |  2 +-
 .../aliaspkg/__init__.py                         |  1 +
 .../aliaspkg/alias_description.py                | 16 ++++++++++++++++
 .../test-ext-autodoc-alias-description/conf.py   | 11 +++++++++++
 .../test-ext-autodoc-alias-description/index.rst |  2 ++
 tests/test_ext_autodoc_configs.py                | 15 +++++++++++++++
 6 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 tests/roots/test-ext-autodoc-alias-description/aliaspkg/__init__.py
 create mode 100644 tests/roots/test-ext-autodoc-alias-description/aliaspkg/alias_description.py
 create mode 100644 tests/roots/test-ext-autodoc-alias-description/conf.py
 create mode 100644 tests/roots/test-ext-autodoc-alias-description/index.rst

diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py
index 70cbc3ba129..e6451b52c9f 100644
--- a/sphinx/ext/autodoc/typehints.py
+++ b/sphinx/ext/autodoc/typehints.py
@@ -27,7 +27,7 @@ def record_typehints(app: Sphinx, objtype: str, name: str, obj: Any,
         if callable(obj):
             annotations = app.env.temp_data.setdefault('annotations', {})
             annotation = annotations.setdefault(name, OrderedDict())
-            sig = inspect.signature(obj)
+            sig = inspect.signature(obj, type_aliases=app.config.autodoc_type_aliases)
             for param in sig.parameters.values():
                 if param.annotation is not param.empty:
                     annotation[param.name] = typing.stringify(param.annotation)
diff --git a/tests/roots/test-ext-autodoc-alias-description/aliaspkg/__init__.py b/tests/roots/test-ext-autodoc-alias-description/aliaspkg/__init__.py
new file mode 100644
index 00000000000..8b137891791
--- /dev/null
+++ b/tests/roots/test-ext-autodoc-alias-description/aliaspkg/__init__.py
@@ -0,0 +1 @@
+
diff --git a/tests/roots/test-ext-autodoc-alias-description/aliaspkg/alias_description.py b/tests/roots/test-ext-autodoc-alias-description/aliaspkg/alias_description.py
new file mode 100644
index 00000000000..2ff6587668d
--- /dev/null
+++ b/tests/roots/test-ext-autodoc-alias-description/aliaspkg/alias_description.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TypeAlias
+
+
+class AliasTarget:
+    """Marker class used for type-alias testing."""
+
+
+AliasName: TypeAlias = AliasTarget
+
+
+def use_alias(value: AliasName) -> AliasName:
+    """Return the provided value unchanged."""
+
+    return value
diff --git a/tests/roots/test-ext-autodoc-alias-description/conf.py b/tests/roots/test-ext-autodoc-alias-description/conf.py
new file mode 100644
index 00000000000..4825b013dd7
--- /dev/null
+++ b/tests/roots/test-ext-autodoc-alias-description/conf.py
@@ -0,0 +1,11 @@
+import os
+import sys
+
+
+sys.path.insert(0, os.path.abspath('.'))
+
+
+extensions = ['sphinx.ext.autodoc']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
diff --git a/tests/roots/test-ext-autodoc-alias-description/index.rst b/tests/roots/test-ext-autodoc-alias-description/index.rst
new file mode 100644
index 00000000000..2f5e8b9a9dd
--- /dev/null
+++ b/tests/roots/test-ext-autodoc-alias-description/index.rst
@@ -0,0 +1,2 @@
+
+.. autofunction:: aliaspkg.alias_description.use_alias
diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py
index 496059b7c9c..5248bada41f 100644
--- a/tests/test_ext_autodoc_configs.py
+++ b/tests/test_ext_autodoc_configs.py
@@ -690,6 +690,21 @@ def test_autodoc_typehints_description_for_invalid_node(app):
     restructuredtext.parse(app, text)  # raises no error
 
 
+@pytest.mark.sphinx('text', testroot='ext-autodoc-alias-description')
+def test_autodoc_typehints_description_respects_aliases(app):
+    app.config.autodoc_typehints = 'description'
+    app.config.autodoc_type_aliases = {
+        'AliasName': 'aliaspkg.alias_description.AliasName',
+    }
+
+    app.build()
+    context = (app.outdir / 'index.txt').read_text()
+
+    assert 'Parameters:\n      **value** (*AliasName*) --' in context
+    assert 'Return type:\n      AliasName' in context
+    assert 'aliaspkg.alias_description.AliasTarget' not in context
+
+
 @pytest.mark.skipif(sys.version_info < (3, 7), reason='python 3.7+ is required.')
 @pytest.mark.sphinx('text', testroot='ext-autodoc')
 def test_autodoc_type_aliases(app):