Use a protocol for RoleFunction (#12513)

Author: AA-Turner

sphinx/ext/inheritance_diagram.py

@@ -385,7 +385,7 @@ def run(self) -> list[Node]:
         # references to real URLs later.  These nodes will eventually be
         # removed from the doctree after we're done with them.
         for name in graph.get_all_class_names():
-            refnodes, x = class_role(  # type: ignore[call-arg,misc]
+            refnodes, x = class_role(  # type: ignore[misc]
                 'class', ':class:`%s`' % name, name, 0, self.state.inliner)
             node.extend(refnodes)
         # Store the graph object so we can use it to generate the

sphinx/util/typing.py

@@ -24,7 +24,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
-    from typing import Final, Literal
+    from typing import Final, Literal, Protocol
 
     from docutils.parsers.rst.states import RSTState as _RSTStateGeneric
     from typing_extensions import TypeAlias, TypeIs
@@ -95,10 +95,25 @@ def is_invalid_builtin_class(obj: Any) -> bool:
 PathMatcher = Callable[[str], bool]
 
 # common role functions
-RoleFunction = Callable[
-    [str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
-    tuple[list[nodes.Node], list[nodes.system_message]],
-]
+if TYPE_CHECKING:
+    class RoleFunction(Protocol):
+        def __call__(
+            self,
+            name: str,
+            rawtext: str,
+            text: str,
+            lineno: int,
+            inliner: Inliner,
+            /,
+            options: dict[str, Any] | None = None,
+            content: Sequence[str] = (),
+        ) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+            ...
+else:
+    RoleFunction = Callable[
+        [str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
+        tuple[list[nodes.Node], list[nodes.system_message]],
+    ]
 
 # A option spec for directive
 OptionSpec = dict[str, Callable[[str], Any]]