doc: Log unused log filter patterns

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>

doc/_extensions/zephyr/warnings_filter.py

@@ -24,7 +24,7 @@ Configuration options
 
 import logging
 import re
-from typing import Dict, Any, List
+from typing import Dict, Any, List, Optional
 
 from sphinx.application import Sphinx
 from sphinx.util.logging import NAMESPACE
@@ -41,6 +41,7 @@ class WarningsFilter(logging.Filter):
         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)
 
@@ -53,7 +54,7 @@ class WarningsFilter(logging.Filter):
 
         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 re.match(expression, str(record.msg)):
+            if expression.match(str(record.msg)):
                 if self._silent:
                     return False
                 else:
@@ -64,6 +65,21 @@ class WarningsFilter(logging.Filter):
         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.
 
@@ -75,8 +91,10 @@ def configure(app: Sphinx) -> None:
     with open(app.config.warnings_filter_config) as f:
         expressions = list()
         for line in f.readlines():
-            if not line.startswith("#"):
-                expressions.append(line.rstrip())
+            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)
@@ -85,11 +103,28 @@ def configure(app: Sphinx) -> None:
         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__,

doc/known-warnings.txt

@@ -1,21 +1,30 @@
 # Each line should contain the regular expression of a known Sphinx warning
 # that should be filtered out
-.*Duplicate C declaration.*\n.*'\.\. c:.*:: dma_config'.*
+
+# Function and (enum or struct) name
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: flash_img_check'.*
-.*Duplicate C declaration.*\n.*'\.\. c:.*:: zsock_fd_set'.*
-.*Duplicate C declaration.*\n.*'\.\. c:.*:: net_if_mcast_monitor'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: fs_statvfs'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*dmic_trigger.*'.*
-.*Duplicate C declaration.*\n.*'\.\. c:.*:: uint16_t id'.*
+.*Duplicate C declaration.*\n.*'\.\. c:.*:: dma_config'.*
+.*Duplicate C declaration.*\n.*'\.\. c:.*:: net_if_mcast_monitor'.*
+.*Duplicate C declaration.*\n.*'\.\. c:struct:: bt_ots_init'.*
+
+# Struct and typedef name
+.*Duplicate C declaration.*\n.*'\.\. c:.*:: zsock_fd_set'.*
+
+# Function and extern function
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_addr_mask_cmp.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_is_addr_bcast.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_addr_lookup.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv6_addr_lookup.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv6_maddr_lookup.*'.*
+
+# Common field names
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct in_addr.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct in6_addr.*'.*
 .*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct net_if.*'.*
-.*Duplicate C declaration.*\n.*'\.\. c:struct:: bt_ots_init'.*
+
+# Clash with field of nested anonymous struct
 .*Duplicate C declaration.*\n.*'\.\. c:member:: enum *bt_mesh_dfd_upload_phase bt_mesh_dfd_srv.phase'.*
 .*Duplicate C declaration.*\n.*'\.\. c:member:: struct *bt_mesh_blob_xfer bt_mesh_dfu_cli.blob'.*
 .*Duplicate C declaration.*\n.*'\.\. c:member:: struct *net_if *\* net_if_mcast_monitor.iface'.