🐛 fix(annotations): link enum variants in Literals (#623)

Literal enum values like `Literal[Color.RED]` rendered as plain code
literals with no cross-reference back to the enum class. Users expect
clickable links to navigate to the enum definition, consistent with
how other type references work throughout the documentation.

Render enum instances inside Literal annotations as `:py:attr:` cross-
references instead of bare ``repr()`` strings. Non-enum literal values
continue to render as inline code.

Closes #363

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -4,6 +4,7 @@
 
 import ast
 import collections.abc
+import enum
 import importlib
 import inspect
 import re
@@ -212,6 +213,17 @@ def fixup_module_name(config: Config, module: str) -> str:
     return module
 
 
+def _format_literal_arg(arg: Any, config: Config) -> str:
+    if isinstance(arg, enum.Enum):
+        enum_cls = type(arg)
+        module = fixup_module_name(config, enum_cls.__module__)
+        fully_qualified = getattr(config, "typehints_fully_qualified", False)
+        qualified = f"{module}.{enum_cls.__qualname__}.{arg.name}" if module else f"{enum_cls.__qualname__}.{arg.name}"
+        prefix = "" if fully_qualified or not module else "~"
+        return f":py:attr:`{prefix}{qualified}`"
+    return f"``{arg!r}``"
+
+
 def format_annotation(annotation: Any, config: Config, *, short_literals: bool = False) -> str:  # noqa: C901, PLR0911, PLR0912, PLR0915, PLR0914
     """
     Format the annotation.
@@ -304,9 +316,10 @@ def format_annotation(annotation: Any, config: Config, *, short_literals: bool =
         fmt = [format_annotation(arg, config, short_literals=short_literals) for arg in args]
         formatted_args = f"\\[\\[{', '.join(fmt[:-1])}], {fmt[-1]}]"
     elif full_name == "typing.Literal":
+        literal_parts = [_format_literal_arg(arg, config) for arg in args]
         if short_literals:
-            return f"\\{' | '.join(f'``{arg!r}``' for arg in args)}"
-        formatted_args = f"\\[{', '.join(f'``{arg!r}``' for arg in args)}]"
+            return f"\\{' | '.join(literal_parts)}"
+        formatted_args = f"\\[{', '.join(literal_parts)}]"
     elif is_bars_union:
         if not args:
             return f":py:{'class' if sys.version_info >= (3, 14) else 'data'}:`{prefix}typing.Union`"

tests/test_sphinx_autodoc_typehints.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import enum
 import re
 import sys
 import types
@@ -60,6 +61,12 @@
 Z = TypeVar("Z", bound="A")
 S = TypeVar("S", bound="miss")  # type: ignore[name-defined] # miss not defined on purpose # noqa: F821
 W = NewType("W", str)
+
+
+class SomeEnum(enum.Enum):
+    VALUE = "val"
+
+
 P = typing_extensions.ParamSpec("P")
 P_args = P.args
 P_kwargs = P.kwargs
@@ -488,6 +495,12 @@ def test_always_use_bars_union(annotation: str, expected_result: str) -> None:
         pytest.param("ClassVar", int, ":py:data:`~typing.ClassVar`\\ \\[:py:class:`int`]", id="ClassVar"),
         pytest.param("NoReturn", None, ":py:data:`~typing.NoReturn`", id="NoReturn"),
         pytest.param("Literal", ("a", 1), ":py:data:`~typing.Literal`\\ \\[``'a'``, ``1``]", id="Literal"),
+        pytest.param(
+            "Literal",
+            (SomeEnum.VALUE,),
+            rf":py:data:`~typing.Literal`\ \[:py:attr:`~{__name__}.SomeEnum.VALUE`]",
+            id="Literal-enum",
+        ),
         pytest.param("Type", None, ":py:class:`~typing.Type`", id="Type-none"),
         pytest.param("Type", (A,), rf":py:class:`~typing.Type`\ \[:py:class:`~{__name__}.A`]", id="Type-A"),
     ],