Deprecate sphinx.roles:Index and make a copy to sphinx.domains.index

4 files changed, 33 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index e86c9985e..a4f62a25a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -17,6 +17,7 @@ Deprecated
 * ``sphinx.io.FiletypeNotFoundError``
 * ``sphinx.io.get_filetype()``
 * ``sphinx.pycode.ModuleAnalyzer.encoding``
+* ``sphinx.roles.Index``
 * ``sphinx.util.detect_encoding()``
 * ``sphinx.util.get_module_source()``
 
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 99bdbe9ac..f1c03ec54 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -61,6 +61,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - N/A
 
+   * - ``sphinx.roles.Index``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexRole``
+
    * - ``sphinx.util.detect_encoding()``
      - 2.4
      - 4.0
diff --git a/sphinx/domains/index.py b/sphinx/domains/index.py
index 9b30ebd64..046fbe158 100644
--- a/sphinx/domains/index.py
+++ b/sphinx/domains/index.py
@@ -11,14 +11,14 @@
 from typing import Any, Dict, Iterable, List, Tuple
 
 from docutils import nodes
-from docutils.nodes import Node
+from docutils.nodes import Node, system_message
 
 from sphinx import addnodes
 from sphinx.domains import Domain
 from sphinx.environment import BuildEnvironment
 from sphinx.util import logging
 from sphinx.util import split_index_msg
-from sphinx.util.docutils import SphinxDirective
+from sphinx.util.docutils import ReferenceRole, SphinxDirective
 from sphinx.util.nodes import process_index_entry
 
 if False:
@@ -84,9 +84,33 @@ class IndexDirective(SphinxDirective):
         return [indexnode, targetnode]
 
 
+class IndexRole(ReferenceRole):
+    def run(self) -> Tuple[List[Node], List[system_message]]:
+        target_id = 'index-%s' % self.env.new_serialno('index')
+        if self.has_explicit_title:
+            # if an explicit target is given, process it as a full entry
+            title = self.title
+            entries = process_index_entry(self.target, target_id)
+        else:
+            # otherwise we just create a single entry
+            if self.target.startswith('!'):
+                title = self.title[1:]
+                entries = [('single', self.target[1:], target_id, 'main', None)]
+            else:
+                title = self.title
+                entries = [('single', self.target, target_id, '', None)]
+
+        index = addnodes.index(entries=entries)
+        target = nodes.target('', '', ids=[target_id])
+        text = nodes.Text(title, title)
+        self.set_source_info(index)
+        return [index, target, text], []
+
+
 def setup(app: "Sphinx") -> Dict[str, Any]:
     app.add_domain(IndexDomain)
     app.add_directive('index', IndexDirective)
+    app.add_role('index', IndexRole())
 
     return {
         'version': 'builtin',
diff --git a/sphinx/roles.py b/sphinx/roles.py
index 5757183ce..477c90ae5 100644
--- a/sphinx/roles.py
+++ b/sphinx/roles.py
@@ -573,6 +573,7 @@ def index_role(typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner,
 
 class Index(ReferenceRole):
     def run(self) -> Tuple[List[Node], List[system_message]]:
+        warnings.warn('Index role is deprecated.', RemovedInSphinx40Warning)
         target_id = 'index-%s' % self.env.new_serialno('index')
         if self.has_explicit_title:
             # if an explicit target is given, process it as a full entry
@@ -607,7 +608,6 @@ specific_docroles = {
     'file': EmphasizedLiteral(),
     'samp': EmphasizedLiteral(),
     'abbr': Abbreviation(),
-    'index': Index(),
 }  # type: Dict[str, RoleFunction]