refactor: autodoc: Move deprecated documenters to autodoc.deprecated package

sphinx/ext/autodoc/__init__.py

@@ -1339,19 +1339,6 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
                 return
 
 
-class SingledispatchFunctionDocumenter(FunctionDocumenter):
-    """
-    Used to be a specialized Documenter subclass for singledispatch'ed functions.
-
-    Retained for backwards compatibility, now does the same as the FunctionDocumenter
-    """
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
 class DecoratorDocumenter(FunctionDocumenter):
     """
     Specialized Documenter subclass for decorator functions.
@@ -1861,24 +1848,6 @@ class DataDocumenter(NewTypeMixin, TypeVarMixin, ModuleLevelDocumenter):
             super().add_content(more_content, no_docstring=no_docstring)
 
 
-class DataDeclarationDocumenter(DataDocumenter):
-    """
-    Specialized Documenter subclass for data that cannot be imported
-    because they are declared without initial value (refs: PEP-526).
-    """
-    objtype = 'datadecl'
-    directivetype = 'data'
-    member_order = 60
-
-    # must be higher than AttributeDocumenter
-    priority = 11
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
 class GenericAliasDocumenter(DataDocumenter):
     """
     Specialized Documenter subclass for GenericAliases.
@@ -1923,21 +1892,6 @@ class NewTypeDataDocumenter(DataDocumenter):
         return inspect.isNewType(member) and isattr
 
 
-class TypeVarDocumenter(DataDocumenter):
-    """
-    Specialized Documenter subclass for TypeVars.
-    """
-
-    objtype = 'typevar'
-    directivetype = 'data'
-    priority = DataDocumenter.priority + 1
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
 class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type: ignore
     """
     Specialized Documenter subclass for methods (normal, static and class).
@@ -2086,19 +2040,6 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
                 return
 
 
-class SingledispatchMethodDocumenter(MethodDocumenter):
-    """
-    Used to be a specialized Documenter subclass for singledispatch'ed methods.
-
-    Retained for backwards compatibility, now does the same as the MethodDocumenter
-    """
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
 class SlotsMixin(DataDocumenterMixinBase):
     """
     Mixin for AttributeDocumenter to provide the feature for supporting __slots__.
@@ -2325,42 +2266,6 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
         self.add_line('   :property:', sourcename)
 
 
-class InstanceAttributeDocumenter(AttributeDocumenter):
-    """
-    Specialized Documenter subclass for attributes that cannot be imported
-    because they are instance attributes (e.g. assigned in __init__).
-    """
-    objtype = 'instanceattribute'
-    directivetype = 'attribute'
-    member_order = 60
-
-    # must be higher than AttributeDocumenter
-    priority = 11
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
-class SlotsAttributeDocumenter(AttributeDocumenter):
-    """
-    Specialized Documenter subclass for attributes that cannot be imported
-    because they are attributes in __slots__.
-    """
-    objtype = 'slotsattribute'
-    directivetype = 'attribute'
-    member_order = 60
-
-    # must be higher than AttributeDocumenter
-    priority = 11
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn("%s is deprecated." % self.__class__.__name__,
-                      RemovedInSphinx50Warning, stacklevel=2)
-        super().__init__(*args, **kwargs)
-
-
 class NewTypeAttributeDocumenter(AttributeDocumenter):
     """
     Specialized Documenter subclass for NewTypes.
@@ -2402,6 +2307,15 @@ def migrate_autodoc_member_order(app: Sphinx, config: Config) -> None:
         config.autodoc_member_order = 'alphabetical'  # type: ignore
 
 
+# for compatibility
+from sphinx.ext.autodoc.deprecated import DataDeclarationDocumenter  # NOQA
+from sphinx.ext.autodoc.deprecated import InstanceAttributeDocumenter  # NOQA
+from sphinx.ext.autodoc.deprecated import SingledispatchFunctionDocumenter  # NOQA
+from sphinx.ext.autodoc.deprecated import SingledispatchMethodDocumenter  # NOQA
+from sphinx.ext.autodoc.deprecated import SlotsAttributeDocumenter  # NOQA
+from sphinx.ext.autodoc.deprecated import TypeVarDocumenter  # NOQA
+
+
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_autodocumenter(ModuleDocumenter)
     app.add_autodocumenter(ClassDocumenter)

sphinx/ext/autodoc/deprecated.py

@@ -0,0 +1,111 @@
+"""
+    sphinx.ext.autodoc.deprecated
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    The deprecated Documenters for autodoc.
+
+    :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import warnings
+from typing import Any
+
+from sphinx.deprecation import RemovedInSphinx50Warning
+from sphinx.ext.autodoc import (AttributeDocumenter, DataDocumenter, FunctionDocumenter,
+                                MethodDocumenter)
+
+
+class SingledispatchFunctionDocumenter(FunctionDocumenter):
+    """
+    Used to be a specialized Documenter subclass for singledispatch'ed functions.
+
+    Retained for backwards compatibility, now does the same as the FunctionDocumenter
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)
+
+
+class DataDeclarationDocumenter(DataDocumenter):
+    """
+    Specialized Documenter subclass for data that cannot be imported
+    because they are declared without initial value (refs: PEP-526).
+    """
+    objtype = 'datadecl'
+    directivetype = 'data'
+    member_order = 60
+
+    # must be higher than AttributeDocumenter
+    priority = 11
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)
+
+
+class TypeVarDocumenter(DataDocumenter):
+    """
+    Specialized Documenter subclass for TypeVars.
+    """
+
+    objtype = 'typevar'
+    directivetype = 'data'
+    priority = DataDocumenter.priority + 1  # type: ignore
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)
+
+
+class SingledispatchMethodDocumenter(MethodDocumenter):
+    """
+    Used to be a specialized Documenter subclass for singledispatch'ed methods.
+
+    Retained for backwards compatibility, now does the same as the MethodDocumenter
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)
+
+
+class InstanceAttributeDocumenter(AttributeDocumenter):
+    """
+    Specialized Documenter subclass for attributes that cannot be imported
+    because they are instance attributes (e.g. assigned in __init__).
+    """
+    objtype = 'instanceattribute'
+    directivetype = 'attribute'
+    member_order = 60
+
+    # must be higher than AttributeDocumenter
+    priority = 11
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)
+
+
+class SlotsAttributeDocumenter(AttributeDocumenter):
+    """
+    Specialized Documenter subclass for attributes that cannot be imported
+    because they are attributes in __slots__.
+    """
+    objtype = 'slotsattribute'
+    directivetype = 'attribute'
+    member_order = 60
+
+    # must be higher than AttributeDocumenter
+    priority = 11
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn("%s is deprecated." % self.__class__.__name__,
+                      RemovedInSphinx50Warning, stacklevel=2)
+        super().__init__(*args, **kwargs)