diff --git a/CHANGES b/CHANGES index 921508d24..e94fb7f30 100644 --- a/CHANGES +++ b/CHANGES @@ -12,6 +12,7 @@ Features added * #1921: Support figure substitutions by :confval:`language` and :confval:`figure_language_filename` * #2245: Add ``latex_elements["passoptionstopackages"]`` option to call PassOptionsToPackages in early stage of preambles. +* Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental) Bugs fixed ---------- diff --git a/doc/config.rst b/doc/config.rst index 40ee674cd..84da0cea3 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -212,6 +212,25 @@ General configuration .. versionadded:: 0.5 +.. confval:: suppress_warnings + + A list of warning types to suppress arbitrary warning messages. + + Sphinx supports following warning types: + + * ref.term + * ref.ref + * ref.numref + * ref.keyword + * ref.citation + * ref.doc + + You can choose from these types. + + Now, this option should be considered *experimental*. + + .. versionadded:: 1.4 + .. confval:: needs_sphinx If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will diff --git a/sphinx/application.py b/sphinx/application.py index 57f29aced..9ff99b691 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -41,6 +41,7 @@ from sphinx.util import pycompat # noqa: imported for side-effects from sphinx.util import import_object from sphinx.util.tags import Tags from sphinx.util.osutil import ENOENT +from sphinx.util.logging import is_suppressed_warning from sphinx.util.console import bold, lightgray, darkgray, darkgreen, \ term_width_line @@ -318,7 +319,7 @@ class Sphinx(object): wfile.flush() self.messagelog.append(message) - def warn(self, message, location=None, prefix='WARNING: '): + 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) @@ -326,12 +327,17 @@ class Sphinx(object): *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: diff --git a/sphinx/config.py b/sphinx/config.py index ba3dc11b4..9434a77c7 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -71,6 +71,7 @@ class Config(object): templates_path = ([], 'html'), template_bridge = (None, 'html', [str]), keep_warnings = (False, 'env'), + suppress_warnings = ([], 'env'), modindex_common_prefix = ([], 'html'), rst_epilog = (None, 'env', [str]), rst_prolog = (None, 'env', [str]), diff --git a/sphinx/environment.py b/sphinx/environment.py index cdb6f92a5..cdfba95f1 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -1540,7 +1540,7 @@ class BuildEnvironment: (node['refdomain'], typ) else: msg = '%r reference target not found: %%(target)s' % typ - self.warn_node(msg % {'target': target}, node) + self.warn_node(msg % {'target': target}, node, type='ref', subtype=typ) def _resolve_doc_reference(self, builder, node, contnode): # directly reference to document by source name; diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py new file mode 100644 index 000000000..ef91b728b --- /dev/null +++ b/sphinx/util/logging.py @@ -0,0 +1,29 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.logging + ~~~~~~~~~~~~~~~~~~~ + + Logging utility functions for Sphinx. + + :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + + +def is_suppressed_warning(type, subtype, suppress_warnings): + """Check the warning is suppressed or not.""" + if type is None: + return False + + for warning_type in suppress_warnings: + if '.' in warning_type: + target, subtarget = warning_type.split('.', 1) + else: + target, subtarget = warning_type, None + + if target == type: + if (subtype is None or subtarget is None or + subtarget == subtype or subtarget == '*'): + return True + + return False diff --git a/tests/test_util_logging.py b/tests/test_util_logging.py new file mode 100644 index 000000000..d88d3cc6d --- /dev/null +++ b/tests/test_util_logging.py @@ -0,0 +1,26 @@ +# -*- coding: utf-8 -*- +""" + test_util_logging + ~~~~~~~~~~~~~~~~~ + + Test logging util. + + :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" +from __future__ import print_function + +from sphinx.util.logging import is_suppressed_warning + + +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