Add :confval:suppress_warnings to supress arbitrary warning message

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
 ----------

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

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:

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]),

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;

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

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