ENH: Improved typing annotation formatting

Fixes #324

Author: kernc

pdoc/__init__.py

@@ -22,9 +22,9 @@
 from functools import lru_cache, reduce, partial
 from itertools import tee, groupby
 from types import ModuleType
-from typing import (
-    cast, Any, Callable, Dict, Generator, Iterable, List, Mapping, Optional, Set, Tuple,
-    Type, TypeVar, Union,
+from typing import (  # noqa: F401
+    cast, Any, Callable, Dict, Generator, Iterable, List, Mapping, NewType,
+    Optional, Set, Tuple, Type, TypeVar, Union,
 )
 from warnings import warn
 
@@ -1242,20 +1242,43 @@ def _link_inheritance(self):
 
 def _formatannotation(annot):
     """
-    Format annotation, properly handling NewType types
+    Format typing annotation with better handling of `typing.NewType`,
+    `typing.Optional`, `nptyping.NDArray` and other types.
 
-    >>> import typing
-    >>> _formatannotation(typing.NewType('MyType', str))
+    # >>> import typing
+    >>> _formatannotation(NewType('MyType', str))
     'MyType'
+    >>> _formatannotation(Optional[Tuple[Optional[int], None]])
+    'Optional[Tuple[Optional[int], None]]'
     """
-    module = getattr(annot, '__module__', '')
-    is_newtype = (getattr(annot, '__qualname__', '').startswith('NewType.') and
-                  module == 'typing')
-    if is_newtype:
-        return annot.__name__
-    if module.startswith('nptyping'):  # GH-231
-        return repr(annot)
-    return inspect.formatannotation(annot)
+    class force_repr(str):
+        __repr__ = str.__str__
+
+    def maybe_replace_reprs(a):
+        # NoneType -> None
+        if a is type(None):  # noqa: E721
+            return force_repr('None')
+        # Union[T, None] -> Optional[T]
+        if (getattr(a, '__origin__', None) is typing.Union and
+                len(a.__args__) == 2 and
+                a.__args__[1] is type(None)):  # noqa: E721
+            t = inspect.formatannotation(maybe_replace_reprs(a.__args__[0]))
+            return force_repr(f'Optional[{t}]')
+        # typing.NewType('T', foo) -> T
+        module = getattr(a, '__module__', '')
+        if module == 'typing' and getattr(a, '__qualname__', '').startswith('NewType.'):
+            return force_repr(a.__name__)
+        # nptyping.types._ndarray.NDArray -> NDArray[(Any,), Int[64]]  # GH-231
+        if module.startswith('nptyping.'):
+            return force_repr(repr(a))
+        # Recurse into args
+        try:
+            a = a.copy_with(tuple([maybe_replace_reprs(arg) for arg in a.__args__]))
+        except Exception:
+            pass  # Not a typing._GenericAlias
+        return a
+
+    return str(inspect.formatannotation(maybe_replace_reprs(annot)))
 
 
 class Function(Doc):

pdoc/test/__init__.py

@@ -1,6 +1,7 @@
 """
 Unit tests for pdoc package.
 """
+import doctest
 import enum
 import inspect
 import os
@@ -125,6 +126,10 @@ class CliTest(unittest.TestCase):
     def setUp(self):
         pdoc.reset()
 
+    def test_project_doctests(self):
+        doctests = doctest.testmod(pdoc)
+        assert not doctests.failed and doctests.attempted, doctests
+
     def _basic_html_assertions(self, expected_files=PUBLIC_FILES):
         # Output directory tree layout is as expected
         files = glob('**', recursive=True)
@@ -927,7 +932,7 @@ def prop(self) -> typing.Optional[int]:
 
         mod = DUMMY_PDOC_MODULE
         cls = pdoc.Class('Foobar', mod, Foobar)
-        self.assertEqual(cls.doc['prop'].type_annotation(), 'Union[int,\N{NBSP}NoneType]')
+        self.assertEqual(cls.doc['prop'].type_annotation(), 'Optional[int]')
 
     @ignore_warnings
     def test_Variable_type_annotation_py36plus(self):