index directive and role emit deprecation warnings for python index-types

CHANGES

@@ -27,6 +27,8 @@ Features added
   old stub file
 * #5923: autodoc: ``:inherited-members:`` option takes a name of anchestor class
   not to document inherited members of the class and uppers
+* :rst:dir:`index` and :rst:role:`index` emit deprecation warnings for python
+  specific index-types
 
 Bugs fixed
 ----------

doc/usage/restructuredtext/directives.rst

@@ -852,6 +852,8 @@ mainly contained in information units, such as the language reference.
       creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
       are Python-specific and therefore deprecated.)
 
+      .. deprecated:: 1.0
+
    You can mark up "main" index entries by prefixing them with an exclamation
    mark.  The references to "main" entries are emphasized in the generated
    index.  For example, if two pages contain ::

sphinx/directives/other.py

@@ -202,7 +202,7 @@ def run(self) -> List[Node]:
         indexnode['inline'] = False
         self.set_source_info(indexnode)
         for entry in arguments:
-            indexnode['entries'].extend(process_index_entry(entry, targetid))
+            indexnode['entries'].extend(process_index_entry(entry, targetid, indexnode))
         return [indexnode, targetnode]
 
 

sphinx/roles.py

@@ -554,7 +554,8 @@ def index_role(typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner,
     target = utils.unescape(target)
     # if an explicit target is given, we can process it as a full entry
     if has_explicit_title:
-        entries = process_index_entry(target, targetid)
+        source, line = inliner.reporter.get_source_and_line(lineno)  # type: ignore
+        entries = process_index_entry(target, targetid, (source, line))
     # otherwise we just create a "single" entry
     else:
         # but allow giving main entry
@@ -573,24 +574,25 @@ 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]]:
+        index = addnodes.index(entries=[])
+        self.set_source_info(index)
+
         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)
+            index['entries'].extend(process_index_entry(self.target, target_id, index))
         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)]
+                index['entries'].append(('single', self.target[1:], target_id, 'main', None))
             else:
                 title = self.title
-                entries = [('single', self.target, target_id, '', None)]
+                index['entries'].append(('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], []
 
 

sphinx/util/nodes.py

@@ -363,7 +363,8 @@ def split_explicit_title(text: str) -> Tuple[bool, str, str]:
 ]
 
 
-def process_index_entry(entry: str, targetid: str) -> List[Tuple[str, str, str, str, str]]:
+def process_index_entry(entry: str, targetid: str, location: Any = None
+                        ) -> List[Tuple[str, str, str, str, str]]:
     from sphinx.domains.python import pairindextypes
 
     indexentries = []  # type: List[Tuple[str, str, str, str, str]]
@@ -375,6 +376,11 @@ def process_index_entry(entry: str, targetid: str) -> List[Tuple[str, str, str,
         entry = entry[1:].lstrip()
     for type in pairindextypes:
         if entry.startswith(type + ':'):
+            logger.warning(__('indextype "%s" is deprecated. '
+                              'Please use "pair: %s; %s" instead.'),
+                           type, type, entry[len(type) + 1:].strip(),
+                           location=location)  # RemovedInSphinx50Warning
+
             value = entry[len(type) + 1:].strip()
             value = pairindextypes[type] + '; ' + value
             indexentries.append(('pair', value, targetid, main, None))