34e50037f0
This allows us to identify any patterns that we can remove or that we didn't realise are no longer in use. This might happen if issues within doxygen or docleaf are resolved. This allows us to remove the pattern: .*Duplicate C declaration.*\n.*'\.\. c:.*:: uint16_t id'.* which does not match anything in the current set up. We also split the filter patterns in known-warnings out into different sections depending on their cause. Also extend the pattern parser to ignore empty lines so that we can have some formatting in the known-warnings file. Signed-off-by: Michael Jones <m.pricejones@gmail.com>
134 lines
3.8 KiB
Python
134 lines
3.8 KiB
Python
"""
|
|
Warnings filter extension
|
|
#########################
|
|
|
|
Copyright (c) 2021 Nordic Semiconductor ASA
|
|
SPDX-License-Identifier: Apache-2.0
|
|
|
|
Introduction
|
|
============
|
|
|
|
This Sphinx plugin can be used to filter out warnings that are known to be false
|
|
positives. The warnings are filtered out based on a set of regular expressions
|
|
given via an configuration file. The format of the configuration file is a
|
|
plain-text file where each line consists of a regular expression. Any lines
|
|
starting with ``#`` will be ignored.
|
|
|
|
Configuration options
|
|
=====================
|
|
|
|
- ``warnings_filter_config``: Configuration file.
|
|
- ``warnings_filter_silent``: Silent flag. If True, warning is hidden. If False
|
|
the warning is converted to an information message and displayed.
|
|
"""
|
|
|
|
import logging
|
|
import re
|
|
from typing import Dict, Any, List, Optional
|
|
|
|
from sphinx.application import Sphinx
|
|
from sphinx.util.logging import NAMESPACE
|
|
|
|
|
|
__version__ = "0.1.0"
|
|
|
|
|
|
class WarningsFilter(logging.Filter):
|
|
"""Warnings filter.
|
|
|
|
Args:
|
|
expressions: List of regular expressions.
|
|
silent: If true, warning is hidden, otherwise it is shown as INFO.
|
|
name: Filter name.
|
|
"""
|
|
|
|
def __init__(self, expressions: List[str], silent: bool, name: str = "") -> None:
|
|
super().__init__(name)
|
|
|
|
self._expressions = expressions
|
|
self._silent = silent
|
|
|
|
def filter(self, record: logging.LogRecord) -> bool:
|
|
if record.levelno != logging.WARNING:
|
|
return True
|
|
|
|
for expression in self._expressions:
|
|
# The message isn't always a string so we convert it before regexing as we can only regex strings
|
|
if expression.match(str(record.msg)):
|
|
if self._silent:
|
|
return False
|
|
else:
|
|
record.levelno = logging.INFO
|
|
record.msg = f"Filtered warning: {record.msg}"
|
|
return True
|
|
|
|
return True
|
|
|
|
|
|
class Expression:
|
|
"""
|
|
Encapsulate a log filter pattern and track if it ever matches a log line.
|
|
"""
|
|
|
|
def __init__(self, pattern):
|
|
self.pattern = pattern
|
|
self.matched = False
|
|
|
|
def match(self, str):
|
|
matches = bool(re.match(self.pattern, str))
|
|
self.matched = matches or self.matched
|
|
return matches
|
|
|
|
|
|
def configure(app: Sphinx) -> None:
|
|
"""Entry point.
|
|
|
|
Args:
|
|
app: Sphinx application instance.
|
|
"""
|
|
|
|
# load expressions from configuration file
|
|
with open(app.config.warnings_filter_config) as f:
|
|
expressions = list()
|
|
for line in f.readlines():
|
|
if line.strip() and not line.startswith("#"):
|
|
expressions.append(Expression(line.rstrip()))
|
|
|
|
app.env.warnings_filter_expressions = expressions
|
|
|
|
# install warnings filter to all the Sphinx logger handlers
|
|
filter = WarningsFilter(expressions, app.config.warnings_filter_silent)
|
|
logger = logging.getLogger(NAMESPACE)
|
|
for handler in logger.handlers:
|
|
handler.filters.insert(0, filter)
|
|
|
|
|
|
def finished(app: Sphinx, exception: Optional[Exception]):
|
|
"""
|
|
Prints out any patterns that have not matched a log line to allow us to clean up any that are not used.
|
|
"""
|
|
if exception:
|
|
# Early exit if there has been an exception as matching data is only
|
|
# valid for complete builds
|
|
return
|
|
|
|
expressions = app.env.warnings_filter_expressions
|
|
|
|
for expression in expressions:
|
|
if not expression.matched:
|
|
logging.warning(f"Unused expression: {expression.pattern}")
|
|
|
|
|
|
def setup(app: Sphinx) -> Dict[str, Any]:
|
|
app.add_config_value("warnings_filter_config", "", "")
|
|
app.add_config_value("warnings_filter_silent", True, "")
|
|
|
|
app.connect("builder-inited", configure)
|
|
app.connect("build-finished", finished)
|
|
|
|
return {
|
|
"version": __version__,
|
|
"parallel_read_safe": True,
|
|
"parallel_write_safe": True,
|
|
}
|