diff --git a/CHANGES b/CHANGES index 35d5d0900..4af1f6542 100644 --- a/CHANGES +++ b/CHANGES @@ -104,6 +104,7 @@ Deprecated * ``sphinx.io.SphinxFileInput.supported`` * ``sphinx.io.SphinxRSTFileInput`` * ``sphinx.registry.SphinxComponentRegistry.add_source_input()`` +* ``sphinx.roles.abbr_role()`` * ``sphinx.testing.util.remove_unicode_literal()`` * ``sphinx.util.attrdict`` * ``sphinx.util.force_decode()`` diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 56f2e7cee..08b9a9e65 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -365,6 +365,11 @@ The following is a list of deprecated interfaces. - 4.0 - ``sphinxcontrib.jsmath`` + * - ``sphinx.roles.abbr_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.Abbreviation`` + * - ``sphinx.testing.util.remove_unicode_literal()`` - 2.0 - 4.0 diff --git a/sphinx/roles.py b/sphinx/roles.py index 53ea144d8..e9a8786ca 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -9,13 +9,16 @@ """ import re +import warnings from docutils import nodes, utils from sphinx import addnodes +from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.errors import SphinxError from sphinx.locale import _ from sphinx.util import ws_re +from sphinx.util.docutils import SphinxRole from sphinx.util.nodes import split_explicit_title, process_index_entry, \ set_role_source_info @@ -338,6 +341,8 @@ _abbr_re = re.compile(r'\((.*)\)$', re.S) def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): # type: (str, str, str, int, Inliner, Dict, List[str]) -> Tuple[List[nodes.Node], List[nodes.system_message]] # NOQA + warnings.warn('abbr_role() is deprecated. Please use Abbrevation class instead.', + RemovedInSphinx40Warning, stacklevel=2) text = utils.unescape(text) m = _abbr_re.search(text) if m is None: @@ -349,6 +354,21 @@ def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [nodes.abbreviation(abbr, abbr, **options)], [] +class Abbreviation(SphinxRole): + abbr_re = re.compile(r'\((.*)\)$', re.S) + + def run(self): + # type: () -> Tuple[List[nodes.Node], List[nodes.system_message]] + matched = self.abbr_re.search(self.text) + if matched: + text = self.text[:matched.start()].strip() + self.options['explanation'] = matched.group(1) + else: + text = self.text + + return [nodes.abbreviation(self.rawtext, text, **self.options)], [] + + def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): # type: (str, str, str, int, Inliner, Dict, List[str]) -> Tuple[List[nodes.Node], List[nodes.system_message]] # NOQA # create new reference target @@ -390,7 +410,7 @@ specific_docroles = { 'menuselection': menusel_role, 'file': emph_literal_role, 'samp': emph_literal_role, - 'abbr': abbr_role, + 'abbr': Abbreviation(), 'index': index_role, } # type: Dict[str, RoleFunction]