Use report_warning instead of print; don't combine regexes into a single pattern for robustness; rename config variable

Author: JasperCraeghs

doc/index.rst

@@ -180,9 +180,13 @@ Configuration values
             'qtogre_doxygen.pdf': '/home/matt/qtogre/doxygen.pdf',
         }
 
-.. confval:: doxylink_parse_exception_ignore_regex_list
+.. confval:: doxylink_parse_error_ignore_regexes
 
-    A list of regular expressions that can be used to ignore specific ``ParseException`` console messages. Default is ``[]``.
+    A list of regular expressions that can be used to ignore specific errors reported from the parser.
+    Default is ``[]``. This is useful if you have a lot of errors that you know are not important.
+    For example, you may want to ignore errors related to a specific namespace.
+    The regular expression is matched against the error message using Python's
+    `re.search <https://docs.python.org/3/library/re.html#re.search>`_ function.
 
 Bug reports
 -----------

sphinxcontrib/doxylink/__init__.py

@@ -4,7 +4,7 @@ def setup(app):
     from .doxylink import setup_doxylink_roles
     app.add_config_value('doxylink', {}, 'env')
     app.add_config_value('doxylink_pdf_files', {}, 'env')
-    app.add_config_value('doxylink_parse_exception_ignore_regex_list',
+    app.add_config_value('doxylink_parse_error_ignore_regexes',
                          default=[], types=[str], rebuild='env')
     app.connect('builder-inited', setup_doxylink_roles)
 

sphinxcontrib/doxylink/doxylink.py

@@ -134,8 +134,8 @@ def is_url(str_to_validate: str) -> bool:
 
 class SymbolMap:
     """A SymbolMap maps symbols to Entries."""
-    def __init__(self, xml_doc: ET.ElementTree, parse_exception_ignore_pattern: Union['re.Pattern', None] = None) -> None:
-        entries = parse_tag_file(xml_doc, parse_exception_ignore_pattern)
+    def __init__(self, xml_doc: ET.ElementTree, parse_error_ignore_regexes: Optional[List[str]] = None) -> None:
+        entries = parse_tag_file(xml_doc, parse_error_ignore_regexes)
 
         # Sort the entry list for use with bisect
         self._entries = sorted(entries)
@@ -225,7 +225,7 @@ def __getitem__(self, item: str) -> Entry:
         return self._disambiguate(symbol, candidates)
 
 
-def parse_tag_file(doc: ET.ElementTree, parse_exception_ignore_pattern: Union['re.Pattern', None]) -> List[Entry]:
+def parse_tag_file(doc: ET.ElementTree, parse_error_ignore_regexes: Optional[List[str]]) -> List[Entry]:
     """
     Takes in an XML tree from a Doxygen tag file and returns a list that looks something like:
 
@@ -290,13 +290,21 @@ def parse_tag_file(doc: ET.ElementTree, parse_exception_ignore_pattern: Union['r
                     entries.append(
                         Entry(name=member_symbol, kind=member_kind, file=member_file, arglist=normalised_arglist))
                 except ParseException as e:
-                    # Check if the parse exception message matches the ignore regular expression, if it does do not print the message
                     message = f'Skipping {member_kind} {member_symbol}{arglist}. Error reported from parser was: {e}'
-                    matched = parse_exception_ignore_pattern.match(message) if parse_exception_ignore_pattern else False
-
-                    if not matched:
-                        print(message)
-
+                    should_report = True
+
+                    if parse_error_ignore_regexes:
+                        for pattern in parse_error_ignore_regexes:
+                            try:
+                                if re.search(pattern, message):
+                                    should_report = False
+                                    break
+                            except re.error:
+                                # Invalid regex pattern - ignore it
+                                continue
+
+                    if should_report:
+                        report_warning(None, message)  # Use None as env since we don't have access to it here
                     continue
             else:
                 # Put the simple things directly into the list
@@ -309,12 +317,15 @@ def join(*args):
     return ''.join(args)
 
 
-def create_role(app, tag_filename, rootdir, cache_name, pdf=""):
-    parse_exception_ignore_regex_list = getattr(app.config, 'doxylink_parse_exception_ignore_regex_list')
-    parse_exception_ignore_pattern = re.compile('|'.join(parse_exception_ignore_regex_list)) if parse_exception_ignore_regex_list else None
+def create_role(app: 'sphinx.application.Sphinx',
+                tag_filename: str,
+                rootdir: str,
+                cache_name: str,
+                pdf: str = "") -> None:
+    parse_error_ignore_regexes = getattr(app.config, 'doxylink_parse_error_ignore_regexes', [])
 
-    if parse_exception_ignore_pattern:
-        report_info(app.env, f'Ignoring parsing exceptions using `{parse_exception_ignore_pattern}`')
+    if parse_error_ignore_regexes:
+        report_info(app.env, f'Using parse error ignore patterns: {", ".join(parse_error_ignore_regexes)}')
 
     # Tidy up the root directory path
     if not rootdir.endswith(('/', '\\')):
@@ -343,22 +354,22 @@ def _parse():
         if not hasattr(app.env, 'doxylink_cache'):
             # no cache present at all, initialise it
             report_info(app.env, 'No cache at all, rebuilding...')
-            mapping = SymbolMap(_parse(), parse_exception_ignore_pattern)
+            mapping = SymbolMap(_parse(), parse_error_ignore_regexes)
             app.env.doxylink_cache = {cache_name: {'mapping': mapping, 'mtime': modification_time, 'version': __version__}}
         elif not app.env.doxylink_cache.get(cache_name):
             # Main cache is there but the specific sub-cache for this tag file is not
             report_info(app.env, 'Sub cache is missing, rebuilding...')
-            mapping = SymbolMap(_parse(), parse_exception_ignore_pattern)
+            mapping = SymbolMap(_parse(), parse_error_ignore_regexes)
             app.env.doxylink_cache[cache_name] = {'mapping': mapping, 'mtime': modification_time, 'version': __version__}
         elif app.env.doxylink_cache[cache_name]['mtime'] < modification_time:
             # tag file has been modified since sub-cache creation
             report_info(app.env, 'Sub-cache is out of date, rebuilding...')
-            mapping = SymbolMap(_parse(), parse_exception_ignore_pattern)
+            mapping = SymbolMap(_parse(), parse_error_ignore_regexes)
             app.env.doxylink_cache[cache_name] = {'mapping': mapping, 'mtime': modification_time}
         elif not app.env.doxylink_cache[cache_name].get('version') or app.env.doxylink_cache[cache_name].get('version') != __version__:
             # sub-cache doesn't have a version or the version doesn't match
             report_info(app.env, 'Sub-cache schema version doesn\'t match, rebuilding...')
-            mapping = SymbolMap(_parse(), parse_exception_ignore_pattern)
+            mapping = SymbolMap(_parse(), parse_error_ignore_regexes)
             app.env.doxylink_cache[cache_name] = {'mapping': mapping, 'mtime': modification_time, 'version': __version__}
         else:
             # The cache is up to date

tests/test_doxylink.py

@@ -197,3 +197,60 @@ def test_process_configuration_warn(rootdir, pdf_filename, builder, msg):
     with LogCapture() as l:
         doxylink.process_configuration(app, 'doxygen/project.tag', rootdir, pdf_filename)
     l.check(('sphinx.sphinxcontrib.doxylink.doxylink', 'WARNING', msg))
+
+
+def test_parse_error_ignore_regexes():
+    # Create a modified tag file content with problematic entries
+    problematic_xml = """<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
+<tagfile>
+    <compound kind="file">
+        <name>test.h</name>
+        <filename>test_8h</filename>
+        <member kind="function">
+            <name>foo</name>
+            <arglist>(transform_pb2.Rotation2f a)</arglist>
+            <anchor>1234</anchor>
+        </member>
+        <member kind="function">
+            <name>bad</name>
+            <arglist>(*int i)</arglist>
+            <anchor>5678</anchor>
+        </member>
+        <member kind="function">
+            <name>baz</name>
+            <arglist>(int i, float f)</arglist>
+            <anchor>9012</anchor>
+        </member>
+        <member kind="function">
+            <name>unexpected</name>
+            <arglist>(*int i)</arglist>
+            <anchor>5678</anchor>
+        </member>
+    </compound>
+</tagfile>"""
+
+    # Write temporary tag file
+    test_tag_file = 'test_temp.tag'
+    with open(test_tag_file, 'w') as f:
+        f.write(problematic_xml)
+
+    try:
+        tag_file = ET.parse(test_tag_file)
+        patterns = [r'kipping function test\.h::foo', r'kipping.*bad']
+
+        with LogCapture() as log:
+            mapping = doxylink.parse_tag_file(tag_file, patterns)
+
+            # Verify that the mapping still contains valid entries
+            assert any(entry.name.endswith('baz') for entry in mapping)
+
+            # Verify that messages matching our patterns were not logged
+            assert not any('test.h::foo' in record.msg for record in log.records)
+            assert not any('bar' in record.msg for record in log.records)
+
+            # Verify other error messages were logged
+            assert any('Skipping' in record.msg for record in log.records)
+
+    finally:
+        if os.path.exists(test_tag_file):
+            os.unlink(test_tag_file)