Identify typing.NewType wrappers and construct annotation references (#64)

Author: gwax

sphinx_autodoc_typehints.py

@@ -117,6 +117,10 @@ def format_annotation(annotation):
         return '{}`~{}.{}`{}'.format(prefix, module, class_name, extra)
     elif annotation is Ellipsis:
         return '...'
+    elif (inspect.isfunction(annotation) and annotation.__module__ == 'typing' and
+          hasattr(annotation, '__name__') and hasattr(annotation, '__supertype__')):
+        return ':py:func:`~typing.NewType`\\(:py:data:`~{}`, {})'.format(
+            annotation.__name__, format_annotation(annotation.__supertype__))
     elif inspect.isclass(annotation) or inspect.isclass(getattr(annotation, '__origin__', None)):
         if not inspect.isclass(annotation):
             annotation_cls = annotation.__origin__

tests/test_sphinx_autodoc_typehints.py

@@ -3,7 +3,8 @@
 import sys
 import textwrap
 from typing import (
-    Any, AnyStr, Callable, Dict, Generic, Mapping, Optional, Pattern, Tuple, TypeVar, Union, Type)
+    Any, AnyStr, Callable, Dict, Generic, Mapping, NewType, Optional, Pattern,
+    Tuple, TypeVar, Union, Type)
 
 from typing_extensions import Protocol
 
@@ -12,6 +13,7 @@
 T = TypeVar('T')
 U = TypeVar('U', covariant=True)
 V = TypeVar('V', contravariant=True)
+W = NewType('W', str)
 
 
 class A:
@@ -89,7 +91,8 @@ class Slotted:
     (C,                             ':py:class:`~%s.C`' % __name__),
     (D,                             ':py:class:`~%s.D`' % __name__),
     (E,                             ':py:class:`~%s.E`\\[\\~T]' % __name__),
-    (E[int],                        ':py:class:`~%s.E`\\[:py:class:`int`]' % __name__)
+    (E[int],                        ':py:class:`~%s.E`\\[:py:class:`int`]' % __name__),
+    (W,                             ':py:func:`~typing.NewType`\\(:py:data:`~W`, :py:class:`str`)')
 ])
 def test_format_annotation(annotation, expected_result):
     result = format_annotation(annotation)