From 96202314c17b7707818c3bffb7aca733bba73bb7 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sun, 6 Oct 2019 17:23:55 +0200 Subject: [PATCH] Remove backslash stripping in domains. Adds several ways to reinstate the old behaviour. Fixes sphinx-doc/sphinx#6462 --- CHANGES | 6 ++++++ doc/usage/configuration.rst | 11 +++++++++++ sphinx/directives/__init__.py | 26 ++++++++++++++++++++++++-- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index d751228ea9a..2de356432fb 100644 --- a/CHANGES +++ b/CHANGES @@ -14,6 +14,12 @@ Incompatible changes * Drop features and APIs deprecated in 1.8.x * #247: autosummary: stub files are overwritten automatically by default. see :confval:`autosummary_generate_overwrite` to change the behavior +* #6462: double backslashes in domain directives are no longer replaced by + single backslashes as default. Each class derived from ObjectDescription + may reenable the stripping for it self. A new configuration value + :confval:`signature_backslash_strip_domain_override` can be used by users + to reenable it per domain as well. Setting it to ``[]`` will reinstate the + old behaviour with backslash stripping in every domain. Deprecated ---------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index dcf1ad4feac..db33a9af5ef 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -626,6 +626,17 @@ General configuration .. versionchanged:: 1.1 Now also removes ````. +.. confval:: signature_backslash_strip_domain_override + + A list of domain names for which to forcibly reinstate backslash stripping. + The value ``None`` means "no domains" while ``[]`` means every domain + (i.e., the behaviour before version 3.0). + Default is ``None``. + When backslash stripping is enabled then every occurrence of ``\\`` in a domain + directive will be changed to ``\``, even within string literals. + + .. versionadded:: 3.0 + .. _intl-options: diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 393df0ca9f5..493b2f328c2 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -58,6 +58,7 @@ class ObjectDescription(SphinxDirective): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True + strip_backslashes = None option_spec = { 'noindex': directives.flag, } # type: Dict[str, DirectiveOption] @@ -93,8 +94,28 @@ def get_signatures(self) -> List[str]: Backslash-escaping of newlines is supported. """ lines = nl_escape_re.sub('', self.arguments[0]).split('\n') - # remove backslashes to support (dummy) escapes; helps Vim highlighting - return [strip_backslash_re.sub(r'\1', line.strip()) for line in lines] + + # Stripping of backslashes can be overridden by the user config, + # otherwise the object it self may have an opinion, and + # otherwise we don't do stripping. + do_stripping = False + conf_stripping = self.env.config.signature_backslash_strip_domain_override + if conf_stripping is None: + # no user config override, use the object opinion if any + if self.strip_backslashes is not None: + do_stripping = self.strip_backslashes + else: + # could be overridden by the user + if len(conf_stripping) == 0: + # override always (i.e., the old behaviour) + do_stripping = True + elif self.domain is not None: + do_stripping = self.domain in conf_stripping + if do_stripping: + # remove backslashes to support (dummy) escapes; helps Vim highlighting + return [strip_backslash_re.sub(r'\1', line.strip()) for line in lines] + else: + return [line.strip() for line in lines] def handle_signature(self, sig: str, signode: desc_signature) -> Any: """ @@ -288,6 +309,7 @@ def run(self) -> List[Node]: def setup(app: "Sphinx") -> Dict[str, Any]: + app.add_config_value("signature_backslash_strip_domain_override", None, 'env') directives.register_directive('default-role', DefaultRole) directives.register_directive('default-domain', DefaultDomain) directives.register_directive('describe', ObjectDescription)