IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Simplify backslash stripping

Browse Source
This commit is contained in:
Jakob Lykke Andersen 2020-03-20 12:55:20 +01:00
parent e0f779ba3d
commit f12a7f1ae2
3 changed files with 10 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
CHANGES
View File

@ -43,11 +43,8 @@ Incompatible changes
* The attribute ``sphinx_cpp_tagname`` in the ``desc_signature_line`` node
has been renamed to ``sphinx_line_type``.
* #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.
single backslashes as default. A new configuration value
:confval:`strip_signature_backslash` can be used by users to reenable it.
Deprecated
----------

13
doc/usage/configuration.rst
View File

@ -634,14 +634,13 @@ General configuration
.. versionchanged:: 1.1
Now also removes ``<BLANKLINE>``.
.. confval:: signature_backslash_strip_domain_override
.. confval:: strip_signature_backslash
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.
Default is ``False``.
When backslash stripping is enabled then every occurrence of ``\\`` in a
domain directive will be changed to ``\``, even within string literals.
This was the behaviour before version 3.0, and setting this variable to
``True`` will reinstate that behaviour.
.. versionadded:: 3.0

24
sphinx/directives/__init__.py
View File

@ -60,7 +60,6 @@ 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]
@ -92,28 +91,9 @@ class ObjectDescription(SphinxDirective):
"""
Retrieve the signatures to document from the directive arguments. By
default, signatures are given as arguments, one per line.
Backslash-escaping of newlines is supported.
"""
lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
# 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:
if self.config.strip_signature_backslash:
# remove backslashes to support (dummy) escapes; helps Vim highlighting
return [strip_backslash_re.sub(r'\1', line.strip()) for line in lines]
else:
@ -318,7 +298,7 @@ deprecated_alias('sphinx.directives',
def setup(app: "Sphinx") -> Dict[str, Any]:
app.add_config_value("signature_backslash_strip_domain_override", None, 'env')
app.add_config_value("strip_signature_backslash", False, 'env')
directives.register_directive('default-role', DefaultRole)
directives.register_directive('default-domain', DefaultDomain)
directives.register_directive('describe', ObjectDescription)