Documentation: port warnings_filter Sphinx extension from Zephyr
ignore known warnings: /home/raiden00/git/RTOS/nuttx/nuttx/Documentation/reference/os/netdev.rst:61: WARNING: Duplicate C declaration, also defined at reference/os/netdev:39. Declaration is '.. c:struct:: net_driver_s'. /home/raiden00/git/RTOS/nuttx/nuttx/Documentation/reference/user/07_signals.rst:180: WARNING: Duplicate C declaration, also defined at reference/user/structures:112. Declaration is '.. c:struct:: sigaction'.
This commit is contained in:
parent
e39ef8563e
commit
6dfe1bf58c
1
.gitignore
vendored
1
.gitignore
vendored
@ -28,6 +28,7 @@
|
||||
*.ddc
|
||||
*.dds
|
||||
*.su
|
||||
*.pyc
|
||||
*~
|
||||
.depend
|
||||
/.config
|
||||
|
19
Documentation/_extensions/__init__.py
Normal file
19
Documentation/_extensions/__init__.py
Normal file
@ -0,0 +1,19 @@
|
||||
##############################################################################
|
||||
# Documentation/_extensions/__init__.py
|
||||
#
|
||||
# Licensed to the Apache Software Foundation (ASF) under one or more
|
||||
# contributor license agreements. See the NOTICE file distributed with
|
||||
# this work for additional information regarding copyright ownership. The
|
||||
# ASF licenses this file to you under the Apache License, Version 2.0 (the
|
||||
# "License"); you may not use this file except in compliance with the
|
||||
# License. You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
#
|
||||
##############################################################################
|
157
Documentation/_extensions/warnings_filter.py
Normal file
157
Documentation/_extensions/warnings_filter.py
Normal file
@ -0,0 +1,157 @@
|
||||
##############################################################################
|
||||
# Documentation/_extenstions/warnings_filter.py
|
||||
#
|
||||
# Licensed to the Apache Software Foundation (ASF) under one or more
|
||||
# contributor license agreements. See the NOTICE file distributed with
|
||||
# this work for additional information regarding copyright ownership. The
|
||||
# ASF licenses this file to you under the Apache License, Version 2.0 (the
|
||||
# "License"); you may not use this file except in compliance with the
|
||||
# License. You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
#
|
||||
##############################################################################
|
||||
|
||||
# This extension was ported from Zephyr. Original file can be found at:
|
||||
#
|
||||
# https://github.com/zephyrproject-rtos/zephyr/blob/main/doc/_extensions/zephyr/warnings_filter.py
|
||||
|
||||
|
||||
"""
|
||||
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 Any, Dict, 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,
|
||||
}
|
@ -31,9 +31,12 @@
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
import sys
|
||||
|
||||
# Add the '_extensions' directory to sys.path, to enable finding Sphinx
|
||||
# extensions within.
|
||||
sys.path.insert(0, "_extensions")
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
@ -55,6 +58,7 @@ extensions = [
|
||||
"sphinx.ext.todo",
|
||||
"sphinx_tabs.tabs",
|
||||
"sphinx_copybutton",
|
||||
"warnings_filter",
|
||||
]
|
||||
|
||||
source_suffix = [".rst", ".md"]
|
||||
@ -124,3 +128,7 @@ linkcheck_ignore = [
|
||||
latex_engine = "lualatex"
|
||||
|
||||
copybutton_exclude = ".linenos, .gp, .go"
|
||||
|
||||
# -- Options for warnings_filter ------------------------------------------
|
||||
|
||||
warnings_filter_config = "known-warnings.txt"
|
||||
|
6
Documentation/known-warnings.txt
Normal file
6
Documentation/known-warnings.txt
Normal file
@ -0,0 +1,6 @@
|
||||
# Each line should contain the regular expression of a known Sphinx warning
|
||||
# that should be filtered out
|
||||
|
||||
# Function and (enum or struct) name
|
||||
.*Duplicate C declaration.*\n.*'\.\. c:.*:: net_driver_s'.*
|
||||
.*Duplicate C declaration.*\n.*'\.\. c:.*:: sigaction'.*
|
5
LICENSE
5
LICENSE
@ -8497,3 +8497,8 @@ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
||||
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
Documentation/_extensions/warnings_filter.py
|
||||
============================================
|
||||
Copyright (c) 2021 Nordic Semiconductor ASA
|
||||
SPDX-License-Identifier: Apache-2.0
|
||||
|
Loading…
Reference in New Issue
Block a user