Add suppress_logging()

As a helper for C/C++ domain, this adds suppress_logging().  It
works as a context manager and suppresses all loggings during the
context temporarily.

sphinx/util/logging.py

@@ -220,16 +220,15 @@ def pending_warnings() -> Generator[logging.Handler, None, None]:
 
 
 @contextmanager
-def pending_logging() -> Generator[MemoryHandler, None, None]:
-    """Contextmanager to pend logging all logs temporary.
+def suppress_logging() -> Generator[MemoryHandler, None, None]:
+    """Contextmanager to suppress logging all logs temporary.
 
     For example::
 
-        >>> with pending_logging():
-        >>>     logger.warning('Warning message!')  # not flushed yet
+        >>> with suppress_logging():
+        >>>     logger.warning('Warning message!')  # suppressed
         >>>     some_long_process()
         >>>
-        Warning message!  # the warning is flushed here
     """
     logger = logging.getLogger(NAMESPACE)
     memhandler = MemoryHandler()
@@ -248,6 +247,24 @@ def pending_logging() -> Generator[MemoryHandler, None, None]:
         for handler in handlers:
             logger.addHandler(handler)
 
+
+@contextmanager
+def pending_logging() -> Generator[MemoryHandler, None, None]:
+    """Contextmanager to pend logging all logs temporary.
+
+    For example::
+
+        >>> with pending_logging():
+        >>>     logger.warning('Warning message!')  # not flushed yet
+        >>>     some_long_process()
+        >>>
+        Warning message!  # the warning is flushed here
+    """
+    logger = logging.getLogger(NAMESPACE)
+    try:
+        with suppress_logging() as memhandler:
+            yield memhandler
+    finally:
         memhandler.flushTo(logger)
 
 

tests/test_util_logging.py

@@ -233,6 +233,20 @@ def test_warning_location(app, status, warning):
     assert colorize('red', 'WARNING: message7') in warning.getvalue()
 
 
+def test_suppress_logging(app, status, warning):
+    logging.setup(app, status, warning)
+    logger = logging.getLogger(__name__)
+
+    logger.warning('message1')
+    with logging.suppress_logging():
+        logger.warning('message2')
+        assert 'WARNING: message1' in warning.getvalue()
+        assert 'WARNING: message2' not in warning.getvalue()
+
+    assert 'WARNING: message1' in warning.getvalue()
+    assert 'WARNING: message2' not in warning.getvalue()
+
+
 def test_pending_warnings(app, status, warning):
     logging.setup(app, status, warning)
     logger = logging.getLogger(__name__)