diff options
| -rw-r--r-- | CHANGES | 1 | ||||
| -rw-r--r-- | doc/extdev/deprecated.rst | 5 | ||||
| -rw-r--r-- | sphinx/domains/index.py | 28 | ||||
| -rw-r--r-- | sphinx/roles.py | 2 |
4 files changed, 33 insertions, 3 deletions
@@ -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] |