diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 97e9547e6..6b5047909 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/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) diff --git a/sphinx/ext/autodoc/deprecated.py b/sphinx/ext/autodoc/deprecated.py new file mode 100644 index 000000000..c6ca13105 --- /dev/null +++ b/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)