diff --git a/CHANGES b/CHANGES index e8721e5cb..c3d63b4f4 100644 --- a/CHANGES +++ b/CHANGES @@ -36,6 +36,7 @@ Deprecated * ``sphinx.ext.autodoc.importer.MockLoader`` * ``sphinx.ext.autodoc.importer.mock()`` * ``sphinx.ext.autosummary.autolink_role()`` +* ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()`` * ``sphinx.util.node.find_source_node()`` * ``sphinx.util.i18n.find_catalog()`` * ``sphinx.util.i18n.find_catalog_files()`` diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index b30537073..99abc56eb 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -141,6 +141,11 @@ The following is a list of deprecated interfaces. - 4.0 - ``sphinx.ext.autosummary.AutoLink`` + * - ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()`` + - 2.1 + - 4.0 + - ``sphinx.directives.ObjectDescription.get_field_type_map()`` + * - ``sphinx.util.node.find_source_node()`` - 2.1 - 4.0 diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index e21eb7f6e..fd7bec586 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -17,12 +17,12 @@ from docutils.parsers.rst import directives, roles from sphinx import addnodes from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias from sphinx.util import docutils -from sphinx.util.docfields import DocFieldTransformer +from sphinx.util.docfields import DocFieldTransformer, TypedField from sphinx.util.docutils import SphinxDirective if False: # For type annotation - from typing import Any, Dict # NOQA + from typing import Any, Dict, Tuple # NOQA from sphinx.application import Sphinx # NOQA from sphinx.util.docfields import Field # NOQA from sphinx.util.typing import DirectiveOption # NOQA @@ -67,6 +67,23 @@ class ObjectDescription(SphinxDirective): objtype = None # type: str indexnode = None # type: addnodes.index + # Warning: this might be removed in future version. Don't touch this from extensions. + _doc_field_type_map = {} # type: Dict[str, Tuple[Field, bool]] + + def get_field_type_map(self): + # type: () -> Dict[str, Tuple[Field, bool]] + if self._doc_field_type_map == {}: + for field in self.doc_field_types: + for name in field.names: + self._doc_field_type_map[name] = (field, False) + + if field.is_typed: + typed_field = cast(TypedField, field) + for name in typed_field.typenames: + self._doc_field_type_map[name] = (field, True) + + return self._doc_field_type_map + def get_signatures(self): # type: () -> List[str] """ diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py index 591ca0786..9b19d229d 100644 --- a/sphinx/util/docfields.py +++ b/sphinx/util/docfields.py @@ -9,15 +9,18 @@ :license: BSD, see LICENSE for details. """ +import warnings from typing import List, Tuple, cast from docutils import nodes from sphinx import addnodes +from sphinx.deprecation import RemovedInSphinx40Warning if False: # For type annotation from typing import Any, Dict, Type, Union # NOQA + from sphinx.directive import ObjectDescription # NOQA from sphinx.environment import BuildEnvironment # NOQA from sphinx.util.typing import TextlikeNode # NOQA @@ -244,15 +247,14 @@ class DocFieldTransformer: typemap = None # type: Dict[str, Tuple[Field, bool]] def __init__(self, directive): - # type: (Any) -> None + # type: (ObjectDescription) -> None self.directive = directive - if '_doc_field_type_map' not in directive.__class__.__dict__: - directive.__class__._doc_field_type_map = \ - self.preprocess_fieldtypes(directive.__class__.doc_field_types) - self.typemap = directive._doc_field_type_map + self.typemap = directive.get_field_type_map() def preprocess_fieldtypes(self, types): # type: (List[Field]) -> Dict[str, Tuple[Field, bool]] + warnings.warn('DocFieldTransformer.preprocess_fieldtypes() is deprecated.', + RemovedInSphinx40Warning) typemap = {} for fieldtype in types: for name in fieldtype.names: