docs/_extensions/warnings_filter.py

0001 """
0002 (taken from https://github.com/zephyrproject-rtos/zephyr/blob/main/doc/_extensions/zephyr/warnings_filter.py)
0003
0004 Warnings filter extension
0005 #########################
0006
0007 Copyright (c) 2021 Nordic Semiconductor ASA
0008 SPDX-License-Identifier: Apache-2.0
0009
0010 Introduction
0011 ============
0012
0013 This Sphinx plugin can be used to filter out warnings that are known to be false
0014 positives. The warnings are filtered out based on a set of regular expressions
0015 given via an configuration file. The format of the configuration file is a
0016 plain-text file where each line consists of a regular expression. Any lines
0017 starting with ``#`` will be ignored.
0018
0019 Configuration options
0020 =====================
0021
0022 - ``warnings_filter_config``: Configuration file.
0023 - ``warnings_filter_silent``: Silent flag. If True, warning is hidden. If False
0024   the warning is converted to an information message and displayed.
0025 """
0026
0027 import logging
0028 import re
0029 from typing import Dict, Any, List
0030
0031 from sphinx.application import Sphinx
0032 from sphinx.class='include' href="/lxr/source/include/gsl/util/">util.logging import NAMESPACE
0033
0034
0035 __version__ = "0.1.0"
0036
0037
0038 class WarningsFilter(logging.Filter):
0039     """Warnings filter.
0040
0041     Args:
0042         expressions: List of regular expressions.
0043         silent: If true, warning is hidden, otherwise it is shown as INFO.
0044         name: Filter name.
0045     """
0046
0047     def __init__(self, expressions: List[str], silent: bool, name: str = "") -> None:
0048         super().__init__(name)
0049
0050         self._expressions = expressions
0051         self._silent = silent
0052
0053     def filter(self, record: logging.LogRecord) -> bool:
0054         for expression in self._expressions:
0055             try:
0056                 if re.match(expression, str(record.msg)):
0057                     if self._silent:
0058                         return False
0059                     else:
0060                         record.levelno = logging.INFO
0061                         record.msg = f"Filtered warning: {record.msg}"
0062                         return True
0063             except:
0064                 print("ERROR??", expression, record.msg, type(record.msg))
0065                 raise
0066
0067         return True
0068
0069
0070 def configure(app: Sphinx) -> None:
0071     """Entry point.
0072
0073     Args:
0074         app: Sphinx application instance.
0075     """
0076
0077     # load expressions from configuration file
0078     with open(app.config.warnings_filter_config) as f:
0079         expressions = list()
0080         for line in f.readlines():
0081             if not line.startswith("#"):
0082                 expressions.append(line.rstrip())
0083
0084     # install warnings filter to all the Sphinx logger handlers
0085     filter = WarningsFilter(expressions, app.config.warnings_filter_silent)
0086     logger = logging.getLogger(NAMESPACE)
0087     for handler in logger.handlers:
0088         handler.filters.insert(0, filter)
0089
0090
0091 def setup(app: Sphinx) -> Dict[str, Any]:
0092     app.add_config_value("warnings_filter_config", "", "")
0093     app.add_config_value("warnings_filter_silent", True, "")
0094
0095     app.connect("builder-inited", configure)
0096
0097     return {
0098         "version": __version__,
0099         "parallel_read_safe": True,
0100         "parallel_write_safe": True,
0101     }