feat: add ability to ignore parse exception console messages

Refs: #55

Author: dambrosio

sphinxcontrib/doxylink/__init__.py

@@ -1,10 +1,13 @@
-__version__ = "1.12.3"
+from . import config
 
+__version__ = "1.12.3"
 
 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(config.DOXYLINK_IGNORE_PARSE_EXCEPTIONS_KEY,
+                         default=False, types=bool, rebuild='env')
     app.connect('builder-inited', setup_doxylink_roles)
 
     return {

sphinxcontrib/doxylink/config.py

@@ -0,0 +1,5 @@
+DOXYLINK_KEY = 'doxylink'
+
+DOXYLINK_IGNORE_PARSE_EXCEPTIONS_KEY = (
+    '_'.join([DOXYLINK_KEY,'ignore_parse_exceptions'])
+)

sphinxcontrib/doxylink/doxylink.py

@@ -19,6 +19,7 @@
     from sphinx.util.logging import getLogger
 
 from . import __version__
+from . import config
 from .parsing import normalise, ParseException
 
 
@@ -134,8 +135,8 @@ def is_url(str_to_validate: str) -> bool:
 
 class SymbolMap:
     """A SymbolMap maps symbols to Entries."""
-    def __init__(self, xml_doc: ET.ElementTree) -> None:
-        entries = parse_tag_file(xml_doc)
+    def __init__(self, xml_doc: ET.ElementTree, ignore_parse_exceptions: bool) -> None:
+        entries = parse_tag_file(xml_doc, ignore_parse_exceptions)
 
         # Sort the entry list for use with bisect
         self._entries = sorted(entries)
@@ -225,7 +226,7 @@ def __getitem__(self, item: str) -> Entry:
         return self._disambiguate(symbol, candidates)
 
 
-def parse_tag_file(doc: ET.ElementTree) -> List[Entry]:
+def parse_tag_file(doc: ET.ElementTree, ignore_parse_exceptions: bool) -> List[Entry]:
     """
     Takes in an XML tree from a Doxygen tag file and returns a list that looks something like:
 
@@ -290,7 +291,9 @@ def parse_tag_file(doc: ET.ElementTree) -> List[Entry]:
                     entries.append(
                         Entry(name=member_symbol, kind=member_kind, file=member_file, arglist=normalised_arglist))
                 except ParseException as e:
-                    print(f'Skipping {member_kind} {member_symbol}{arglist}. Error reported from parser was: {e}')
+                    if not ignore_parse_exceptions:
+                        print(f'Skipping {member_kind} {member_symbol}{arglist}. Error reported from parser was: {e}')
+                    continue
             else:
                 # Put the simple things directly into the list
                 entries.append(Entry(name=member_symbol, kind=member_kind, file=member_file, arglist=None))
@@ -303,6 +306,10 @@ def join(*args):
 
 
 def create_role(app, tag_filename, rootdir, cache_name, pdf=""):
+    ignore_parse_exceptions = getattr(app.config, config.DOXYLINK_IGNORE_PARSE_EXCEPTIONS_KEY)
+    if ignore_parse_exceptions:
+        report_info(app.env,"Ignoring parsing exceptions")
+
     # Tidy up the root directory path
     if not rootdir.endswith(('/', '\\')):
         rootdir = join(rootdir, os.sep)
@@ -330,22 +337,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())
+            mapping = SymbolMap(_parse(), ignore_parse_exceptions)
             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())
+            mapping = SymbolMap(_parse(), ignore_parse_exceptions)
             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())
+            mapping = SymbolMap(_parse(), ignore_parse_exceptions)
             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())
+            mapping = SymbolMap(_parse(), ignore_parse_exceptions)
             app.env.doxylink_cache[cache_name] = {'mapping': mapping, 'mtime': modification_time, 'version': __version__}
         else:
             # The cache is up to date