Deprecate abbreviation node (refs: #5720)

CHANGES

@@ -46,6 +46,7 @@ Deprecated
   is_meta_keywords()``
 * The ``suffix`` argument of ``env.doc2path()`` is deprecated.
 * The string style ``base`` argument of ``env.doc2path()`` is deprecated.
+* ``sphinx.addnodes.abbreviation``
 * ``sphinx.application.Sphinx._setting_up_extension``
 * ``sphinx.config.check_unicode()``
 * ``sphinx.ext.autodoc.importer._MockImporter``

doc/extdev/index.rst

@@ -147,6 +147,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``os.path.join()``
 
+   * - ``sphinx.addnodes.abbreviation``
+     - 2.0
+     - 4.0
+     - ``docutils.nodes.abbreviation``
+
    * - ``sphinx.config.check_unicode()``
      - 2.0
      - 4.0

sphinx/addnodes.py

@@ -13,7 +13,7 @@ import warnings
 
 from docutils import nodes
 
-from sphinx.deprecation import RemovedInSphinx30Warning
+from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 
 if False:
     # For type annotation
@@ -344,8 +344,18 @@ class literal_strong(nodes.strong, not_smartquotable):
     """
 
 
-class abbreviation(nodes.Inline, nodes.TextElement):
-    """Node for abbreviations with explanations."""
+class abbreviation(nodes.abbreviation):
+    """Node for abbreviations with explanations.
+
+    .. deprecated:: 2.0
+    """
+
+    def __init__(self, rawsource='', text='', *children, **attributes):
+        # type: (str, str, *nodes.Node, **Any) -> None
+        warnings.warn("abbrevition node for Sphinx was replaced by docutils'.",
+                      RemovedInSphinx40Warning, stacklevel=2)
+
+        super(abbreviation, self).__init__(rawsource, text, *children, **attributes)
 
 
 class manpage(nodes.Inline, nodes.FixedTextElement):
@@ -389,7 +399,6 @@ def setup(app):
     app.add_node(download_reference)
     app.add_node(literal_emphasis)
     app.add_node(literal_strong)
-    app.add_node(abbreviation, override=True)
     app.add_node(manpage)
 
     return {

sphinx/roles.py

@@ -343,12 +343,12 @@ def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     text = utils.unescape(text)
     m = _abbr_re.search(text)
     if m is None:
-        return [addnodes.abbreviation(text, text, **options)], []
+        return [nodes.abbreviation(text, text, **options)], []
     abbr = text[:m.start()].strip()
     expl = m.group(1)
     options = options.copy()
     options['explanation'] = expl
-    return [addnodes.abbreviation(abbr, abbr, **options)], []
+    return [nodes.abbreviation(abbr, abbr, **options)], []
 
 
 def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):