feat(nodes): add helper for creating index entries

Author: dinhnguyenminhhoang

CHANGES.rst

@@ -4,6 +4,9 @@ Release 9.1.1 (in development)
 Bugs fixed
 ----------
 
+* #2914: Add ``sphinx.util.nodes.make_index()`` for extensions to create
+  index entries and their cross-reference targets.
+
 * #14465: LaTeX: PDF build crash since LaTeX June 2026 release if tables are
   styled with ``'colorrows'`` (which is the default).
   Patch by Jean-François B.

doc/extdev/utils.rst

@@ -37,6 +37,8 @@ Utility functions
 
 .. autofunction:: sphinx.util.parsing.nested_parse_to_nodes
 
+.. autofunction:: sphinx.util.nodes.make_index
+
 
 Utility types
 -------------

sphinx/domains/index.py

@@ -12,7 +12,7 @@
 from sphinx.util import logging
 from sphinx.util.docutils import ReferenceRole, SphinxDirective
 from sphinx.util.index_entries import split_index_msg
-from sphinx.util.nodes import process_index_entry
+from sphinx.util.nodes import make_index, process_index_entry
 
 if TYPE_CHECKING:
     from collections.abc import Set
@@ -78,19 +78,15 @@ def run(self) -> list[Node]:
         if 'name' in self.options:
             targetname = self.options['name']
             targetnode = nodes.target('', '', names=[targetname])
+            self.state.document.note_explicit_target(targetnode)
+            targetid = targetnode['ids'][0]
+            indexnode = addnodes.index(entries=[], inline=False)
         else:
-            targetid = 'index-%s' % self.env.new_serialno('index')
-            targetnode = nodes.target('', '', ids=[targetid])
-
-        self.state.document.note_explicit_target(targetnode)
-        indexnode = addnodes.index()
-        indexnode['entries'] = []
-        indexnode['inline'] = False
+            index_nodes, targetid = make_index(self.state.document, [], inline=False)
+            indexnode, targetnode = index_nodes
         self.set_source_info(indexnode)
         for entry in arguments:
-            indexnode['entries'].extend(
-                process_index_entry(entry, targetnode['ids'][0])
-            )
+            indexnode['entries'].extend(process_index_entry(entry, targetid))
         return [indexnode, targetnode]
 
 
@@ -110,8 +106,14 @@ def run(self) -> tuple[list[Node], list[system_message]]:
                 title = self.title
                 entries = [('single', self.target, target_id, '', None)]
 
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
+        index_nodes, _targetid = make_index(
+            self.inliner.document,
+            [],
+            targetid=target_id,
+            inline=True,
+        )
+        index, target = index_nodes
+        index['entries'] = entries
         text = nodes.Text(title)
         self.set_source_info(index)
         return [index, target, text], []

sphinx/domains/std/__init__.py

@@ -19,7 +19,7 @@
 from sphinx.roles import EmphasizedLiteral, XRefRole
 from sphinx.util import docname_join, logging, ws_re
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.nodes import clean_astext, make_id, make_refnode
+from sphinx.util.nodes import clean_astext, make_id, make_index, make_refnode
 from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
@@ -101,14 +101,15 @@ def result_nodes(
         if not is_ref:
             return [node], []
         varname = node['reftarget']
-        tgtid = 'index-%s' % env.new_serialno('index')
-        indexnode = addnodes.index()
-        indexnode['entries'] = [
-            ('single', varname, tgtid, '', None),
-            ('single', _('environment variable; %s') % varname, tgtid, '', None),
-        ]
-        targetnode = nodes.target('', '', ids=[tgtid])
-        document.note_explicit_target(targetnode)
+        index_nodes, _targetid = make_index(
+            document,
+            [
+                ('single', varname),
+                ('single', _('environment variable; %s') % varname),
+            ],
+            inline=True,
+        )
+        indexnode, targetnode = index_nodes
         return [indexnode, targetnode, node], []
 
 
@@ -200,25 +201,35 @@ def run(self) -> list[Node]:
         # normalize whitespace in fullname like XRefRole does
         fullname = ws_re.sub(' ', self.arguments[0].strip())
         node_id = make_id(self.env, self.state.document, self.name, fullname)
-        node = nodes.target('', '', ids=[node_id])
-        self.set_source_info(node)
-        self.state.document.note_explicit_target(node)
-        ret: list[Node] = [node]
         if self.indextemplate:
             indexentry = self.indextemplate % (fullname,)
             indextype = 'single'
             colon = indexentry.find(':')
             if colon != -1:
                 indextype = indexentry[:colon].strip()
                 indexentry = indexentry[colon + 1 :].strip()
-            inode = addnodes.index(entries=[(indextype, indexentry, node_id, '', None)])
-            ret.insert(0, inode)
+            index_nodes, _targetid = make_index(
+                self.state.document,
+                [(indextype, indexentry)],
+                targetid=node_id,
+                inline=True,
+            )
+            indexnode, targetnode = index_nodes
+            self.set_source_info(targetnode)
+            ret = [indexnode, targetnode]
+            target_location = targetnode
+        else:
+            node = nodes.target('', '', ids=[node_id])
+            self.set_source_info(node)
+            self.state.document.note_explicit_target(node)
+            ret = [node]
+            target_location = node
         name = self.name
         if ':' in self.name:
             name = self.name.partition(':')[-1]
 
         std = self.env.domains.standard_domain
-        std.note_object(name, fullname, node_id, location=node)
+        std.note_object(name, fullname, node_id, location=target_location)
 
         return ret
 

sphinx/roles.py

@@ -13,6 +13,7 @@
 from sphinx.locale import _, __
 from sphinx.util import ws_re
 from sphinx.util.docutils import ReferenceRole, SphinxRole, _normalize_options
+from sphinx.util.nodes import make_index
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -198,20 +199,17 @@ class CVE(ReferenceRole):
     _BASE_URL: Final = 'https://www.cve.org/CVERecord?id=CVE-'
 
     def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = f'index-{self.env.new_serialno("index")}'
-        entries = [
-            (
-                'single',
-                _('Common Vulnerabilities and Exposures; CVE %s') % self.target,
-                target_id,
-                '',
-                None,
-            )
-        ]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
+        index_nodes, _targetid = make_index(
+            self.inliner.document,
+            [
+                (
+                    'single',
+                    _('Common Vulnerabilities and Exposures; CVE %s') % self.target,
+                )
+            ],
+            inline=True,
+        )
+        index, target = index_nodes
 
         try:
             refuri = self.build_uri()
@@ -243,20 +241,12 @@ class CWE(ReferenceRole):
     _BASE_URL: Final = 'https://cwe.mitre.org/data/definitions/'
 
     def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = f'index-{self.env.new_serialno("index")}'
-        entries = [
-            (
-                'single',
-                _('Common Weakness Enumeration; CWE %s') % self.target,
-                target_id,
-                '',
-                None,
-            )
-        ]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
+        index_nodes, _targetid = make_index(
+            self.inliner.document,
+            [('single', _('Common Weakness Enumeration; CWE %s') % self.target)],
+            inline=True,
+        )
+        index, target = index_nodes
 
         try:
             refuri = self.build_uri()
@@ -286,20 +276,12 @@ def build_uri(self) -> str:
 
 class PEP(ReferenceRole):
     def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = 'index-%s' % self.env.new_serialno('index')
-        entries = [
-            (
-                'single',
-                _('Python Enhancement Proposals; PEP %s') % self.target,
-                target_id,
-                '',
-                None,
-            )
-        ]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
+        index_nodes, _targetid = make_index(
+            self.inliner.document,
+            [('single', _('Python Enhancement Proposals; PEP %s') % self.target)],
+            inline=True,
+        )
+        index, target = index_nodes
 
         try:
             refuri = self.build_uri()
@@ -331,13 +313,13 @@ def build_uri(self) -> str:
 
 class RFC(ReferenceRole):
     def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = 'index-%s' % self.env.new_serialno('index')
         formatted_target = _format_rfc_target(self.target)
-        entries = [('single', f'RFC; {formatted_target}', target_id, '', None)]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
+        index_nodes, _targetid = make_index(
+            self.inliner.document,
+            [('single', f'RFC; {formatted_target}')],
+            inline=True,
+        )
+        index, target = index_nodes
 
         try:
             refuri = self.build_uri()

sphinx/util/nodes.py

@@ -637,6 +637,43 @@ def make_id(
     return node_id
 
 
+def make_index(
+    document: nodes.document,
+    entries: Iterable[tuple[str, str]],
+    *,
+    indexname: str = 'index',
+    targetid: str | None = None,
+    inline: bool = False,
+) -> tuple[list[Node], str]:
+    """Create an index node and its target node.
+
+    ``entries`` contains pairs of index entry type and entry text. The helper
+    expands each pair to the full index entry tuple expected by Sphinx and
+    points all entries at the generated (or supplied) target ID.
+
+    :param document: the document receiving the target node
+    :param entries: index entry type and text pairs
+    :param indexname: serial number prefix used when generating a target ID
+    :param targetid: explicit target ID; generated when omitted
+    :param inline: whether the index node is inserted inline
+    :return: the index and target nodes, followed by the target ID
+    """
+    if targetid is None:
+        env = document.settings.env
+        targetid = f'{indexname}-{env.new_serialno(indexname)}'
+
+    targetnode = nodes.target('', '', ids=[targetid])
+    document.note_explicit_target(targetnode)
+    indexnode = addnodes.index(
+        entries=[
+            (entry_type, entry_text, targetid, '', None)
+            for entry_type, entry_text in entries
+        ],
+        inline=inline,
+    )
+    return [indexnode, targetnode], targetid
+
+
 def find_pending_xref_condition(
     node: addnodes.pending_xref, condition: str
 ) -> Element | None:

tests/test_util/test_util_nodes.py

@@ -10,13 +10,15 @@
 from docutils.parsers import rst
 from docutils.utils import new_document
 
+from sphinx import addnodes
 from sphinx.transforms import ApplySourceWorkaround
 from sphinx.util.nodes import (
     NodeMatcher,
     apply_source_workaround,
     clean_astext,
     extract_messages,
     make_id,
+    make_index,
     split_explicit_title,
 )
 
@@ -240,6 +242,46 @@ def test_make_id_sequential(app):
     assert make_id(app.env, document, 'term') == 'term-1'
 
 
+@pytest.mark.sphinx('html', testroot='root')
+def test_make_index(app):
+    document = create_new_document()
+    document.settings.env = app.env
+
+    index_nodes, target_id = make_index(
+        document,
+        [('single', 'first'), ('pair', 'second')],
+    )
+
+    assert target_id == 'index-0'
+    assert isinstance(index_nodes[0], addnodes.index)
+    assert isinstance(index_nodes[1], nodes.target)
+    assert index_nodes[0]['entries'] == [
+        ('single', 'first', target_id, '', None),
+        ('pair', 'second', target_id, '', None),
+    ]
+    assert index_nodes[0]['inline'] is False
+    assert index_nodes[1]['ids'] == [target_id]
+    assert document.ids[target_id] is index_nodes[1]
+
+
+@pytest.mark.sphinx('html', testroot='root')
+def test_make_index_custom_target_and_inline(app):
+    document = create_new_document()
+    document.settings.env = app.env
+
+    index_nodes, target_id = make_index(
+        document,
+        [('single', 'entry')],
+        indexname='custom',
+        targetid='custom-target',
+        inline=True,
+    )
+
+    assert target_id == 'custom-target'
+    assert index_nodes[0]['inline'] is True
+    assert index_nodes[0]['entries'] == [('single', 'entry', target_id, '', None)]
+
+
 @pytest.mark.parametrize(
     ('title', 'expected'),
     [