deprecate formatargspec() and format_annotation()

CHANGES

@@ -19,6 +19,8 @@ Deprecated
 
 * using a string value for :confval:`html_sidebars` is deprecated and only list
   values will be accepted at 2.0.
+* ``format_annotation()`` and ``formatargspec()`` is deprecated.  Please use
+  ``sphinx.util.inspect.Signature`` instead.
 
 Features added
 --------------

sphinx/ext/autodoc/inspector.py

@@ -10,9 +10,11 @@
 """
 
 import typing
+import warnings
 
 from six import StringIO, string_types
 
+from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.util.inspect import object_description
 
 if False:
@@ -29,6 +31,9 @@ def format_annotation(annotation):
 
     Displaying complex types from ``typing`` relies on its private API.
     """
+    warnings.warn('format_annotation() is now deprecated.  '
+                  'Please use sphinx.util.inspect.Signature instead.',
+                  RemovedInSphinx20Warning)
     if isinstance(annotation, typing.TypeVar):  # type: ignore
         return annotation.__name__
     if annotation == Ellipsis:
@@ -107,6 +112,9 @@ def formatargspec(function, args, varargs=None, varkw=None, defaults=None,
     An enhanced version of ``inspect.formatargspec()`` that handles typing
     annotations better.
     """
+    warnings.warn('formatargspec() is now deprecated.  '
+                  'Please use sphinx.util.inspect.Signature instead.',
+                  RemovedInSphinx20Warning)
 
     def format_arg_with_annotation(name):
         # type: (str) -> str

tests/test_autodoc.py

@@ -1108,53 +1108,3 @@ class EnumCls(enum.Enum):
     val2 = 23  #: doc for val2
     val3 = 34
     """doc for val3"""
-
-
-def test_type_hints():
-    from sphinx.ext.autodoc import formatargspec
-    from sphinx.util.inspect import getargspec
-
-    try:
-        from typing_test_data import f0, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11
-    except (ImportError, SyntaxError):
-        pytest.skip('Cannot import Python code with function annotations')
-
-    def verify_arg_spec(f, expected):
-        assert formatargspec(f, *getargspec(f)) == expected
-
-    # Class annotations
-    verify_arg_spec(f0, '(x: int, y: numbers.Integral) -> None')
-
-    # Generic types with concrete parameters
-    verify_arg_spec(f1, '(x: typing.List[int]) -> typing.List[int]')
-
-    # TypeVars and generic types with TypeVars
-    verify_arg_spec(f2, '(x: typing.List[T],'
-                        ' y: typing.List[T_co],'
-                        ' z: T) -> typing.List[T_contra]')
-
-    # Union types
-    verify_arg_spec(f3, '(x: typing.Union[str, numbers.Integral]) -> None')
-
-    # Quoted annotations
-    verify_arg_spec(f4, '(x: str, y: str) -> None')
-
-    # Keyword-only arguments
-    verify_arg_spec(f5, '(x: int, *, y: str, z: str) -> None')
-
-    # Keyword-only arguments with varargs
-    verify_arg_spec(f6, '(x: int, *args, y: str, z: str) -> None')
-
-    # Space around '=' for defaults
-    verify_arg_spec(f7, '(x: int = None, y: dict = {}) -> None')
-
-    # Callable types
-    verify_arg_spec(f8, '(x: typing.Callable[[int, str], int]) -> None')
-    verify_arg_spec(f9, '(x: typing.Callable) -> None')
-
-    # Tuple types
-    verify_arg_spec(f10, '(x: typing.Tuple[int, str],'
-                         ' y: typing.Tuple[int, ...]) -> None')
-
-    # Instance annotations
-    verify_arg_spec(f11, '(x: CustomAnnotation, y: 123) -> None')