def test_is_suppressed_warning():
suppress_warnings = ["ref", "files.*", "rest.duplicated_labels"]
assert is_suppressed_warning(None, None, suppress_warnings) is False
assert is_suppressed_warning("ref", None, suppress_warnings) is True
assert is_suppressed_warning("ref", "numref", suppress_warnings) is True
assert is_suppressed_warning("ref", "option", suppress_warnings) is True
assert is_suppressed_warning("files", "image", suppress_warnings) is True
assert is_suppressed_warning("files", "stylesheet", suppress_warnings) is True
assert is_suppressed_warning("rest", None, suppress_warnings) is False
assert is_suppressed_warning("rest", "syntax", suppress_warnings) is False
assert is_suppressed_warning("rest", "duplicated_labels", suppress_warnings) is True
def warn(self, message, location=None, prefix='WARNING: ',
type=None, subtype=None, colorfunc=darkred):
# type: (unicode, unicode, unicode, unicode, unicode, Callable) -> None
"""Emit a warning.
If *location* is given, it should either be a tuple of (docname, lineno)
or a string describing the location of the warning as well as possible.
*prefix* usually should not be changed.
*type* and *subtype* are used to suppress warnings with :confval:`suppress_warnings`.
.. note::
For warnings emitted during parsing, you should use
:meth:`.BuildEnvironment.warn` since that will collect all
warnings during parsing for later output.
"""
if is_suppressed_warning(type, subtype, self.config.suppress_warnings):
return
if isinstance(location, tuple):
docname, lineno = location
if docname:
location = '%s:%s' % (self.env.doc2path(docname), lineno or '')
else:
location = None
warntext = location and '%s: %s%s\n' % (location, prefix, message) or \
'%s%s\n' % (prefix, message)
if self.warningiserror:
raise SphinxWarning(warntext)
self._warncount += 1
self._log(colorfunc(warntext), self._warning, True)
def create_warning(
document: nodes.document,
message: str,
*,
line: int | None = None,
append_to: nodes.Element | None = None,
wtype: str = "myst",
subtype: str = "other",
) -> nodes.system_message | None:
"""Generate a warning, logging it if necessary.
If the warning type is listed in the ``suppress_warnings`` configuration,
then ``None`` will be returned and no warning logged.
"""
message = f"{message} [{wtype}.{subtype}]"
kwargs = {"line": line} if line is not None else {}
if logging.is_suppressed_warning(
wtype, subtype,
document.settings.env.app.config.suppress_warnings):
return None
msg_node = document.reporter.warning(message, **kwargs)
if append_to is not None:
append_to.append(msg_node)
return None
def warn(self, message, location=None, prefix='WARNING: ', type=None, subtype=None):
"""Emit a warning.
If *location* is given, it should either be a tuple of (docname, lineno)
or a string describing the location of the warning as well as possible.
*prefix* usually should not be changed.
*type* and *subtype* are used to suppress warnings with :confval:`suppress_warnings`.
.. note::
For warnings emitted during parsing, you should use
:meth:`.BuildEnvironment.warn` since that will collect all
warnings during parsing for later output.
"""
if is_suppressed_warning(type, subtype, self.config.suppress_warnings):
return
if isinstance(location, tuple):
docname, lineno = location
if docname:
location = '%s:%s' % (self.env.doc2path(docname), lineno or '')
else:
location = None
warntext = location and '%s: %s%s\n' % (location, prefix, message) or \
'%s%s\n' % (prefix, message)
if self.warningiserror:
raise SphinxWarning(warntext)
self._warncount += 1
self._log(warntext, self._warning, True)
def test_is_suppressed_warning():
suppress_warnings = ["ref", "files.*", "rest.duplicated_labels"]
assert is_suppressed_warning(None, None, suppress_warnings) is False
assert is_suppressed_warning("ref", None, suppress_warnings) is True
assert is_suppressed_warning("ref", "numref", suppress_warnings) is True
assert is_suppressed_warning("ref", "option", suppress_warnings) is True
assert is_suppressed_warning("files", "image", suppress_warnings) is True
assert is_suppressed_warning("files", "stylesheet", suppress_warnings) is True
assert is_suppressed_warning("rest", "syntax", suppress_warnings) is False
assert is_suppressed_warning("rest", "duplicated_labels", suppress_warnings) is True
def log_override_warning(app: Sphinx, version: int, current: str,
new: str) -> None:
"""Log a warning if MathJax configuration being overridden."""
if logging.is_suppressed_warning("myst", "mathjax",
app.config.suppress_warnings):
return
config_name = ("mathjax3_config['options']['processHtmlClass']" if version
== 3 else "mathjax_config['tex2jax']['processClass']")
logger.warning(
f"`{config_name}` is being overridden by myst-parser: '{current}' -> '{new}'. "
"Set `suppress_warnings=['myst.mathjax']` to ignore this warning, or "
"`myst_update_mathjax=False` if this is undesirable.")
def create_warning(
self,
message: str,
*,
line: Optional[int] = None,
append_to: Optional[nodes.Element] = None,
wtype: str = "myst",
subtype: str = "other",
) -> Optional[nodes.system_message]:
"""Generate a warning, logging it if necessary.
If the warning type is listed in the ``suppress_warnings`` configuration,
then ``None`` will be returned and no warning logged.
"""
message = f"{message} [{wtype}.{subtype}]"
kwargs = {"line": line} if line is not None else {}
if not logging.is_suppressed_warning(
wtype, subtype, self.doc_env.app.config.suppress_warnings):
msg_node = self.reporter.warning(message, **kwargs)
if append_to is not None:
append_to.append(msg_node)
return None
def create_warning(
app: Sphinx,
doctree: nodes.document,
category: str,
message: str,
*,
line: Optional[int] = None,
append_to: Optional[nodes.Element] = None,
wtype: str = "etoc",
) -> Optional[nodes.system_message]:
"""Generate a warning, logging it if necessary.
If the warning type is listed in the ``suppress_warnings`` configuration,
then ``None`` will be returned and no warning logged.
"""
message = f"{message} [{wtype}.{category}]"
kwargs = {"line": line} if line is not None else {}
if not logging.is_suppressed_warning(wtype, category, app.config.suppress_warnings):
msg_node = doctree.reporter.warning(message, **kwargs)
if append_to is not None:
append_to.append(msg_node)
return msg_node
return None