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
