docs: Sphinx >=7.4.0 breaks warning ignore script

[AJPfleger]

Problem

The logging in sphinx changed slightly in 7.3.7 -> 7.4.0. This breaks our warnings_filter.py-script, that helps to ignore false positives. The issue persists until at least 8.1.3.

Details

It is clear, why this set of warnings does not work and others (e.g. Duplicate C++ declaration, ...) do. There was a change in Sphinx regarding the handling of the messages from:

logger.warning(msg % target, ...

to

logger.warning(msg, target, ...

. This might change the time, when the expression is evaluated.

Message in log

/home/runner/work/acts/acts/docs/api/api.md:60: WARNING: undefined label: 'class_acts_1_1_convex_polygon_bounds_3_01_polygon_dynamic_01_4'
/home/runner/work/acts/acts/docs/api/api.md:171: WARNING: undefined label: 'class_acts_1_1_axis_3_01_axis_type_1_1_equidistant_00_01bdt_01_4'
/home/runner/work/acts/acts/docs/api/api.md:171: WARNING: undefined label: 'class_acts_1_1_axis_3_01_axis_type_1_1_variable_00_01bdt_01_4'
/home/runner/work/acts/acts/docs/api/api.md:177: WARNING: undefined label: 'class_acts_1_1_grid_surface_material_t'

Handled object until 7.3.7

 <LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: 'class_acts_1_1_convex_polygon_bounds_3_01_polygon_dynamic_01_4'">
 <LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: 'class_acts_1_1_axis_3_01_axis_type_1_1_equidistant_00_01bdt_01_4'">
 <LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: 'class_acts_1_1_axis_3_01_axis_type_1_1_variable_00_01bdt_01_4'">
 <LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: 'class_acts_1_1_grid_surface_material_t'">

Handled object since 7.4.0

<LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: %r">
<LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: %r">
<LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: %r">
<LogRecord: sphinx.sphinx.domains.std, 30, /home/runner/.local/lib/python3.10/site-packages/sphinx/util/logging.py, 131, "undefined label: %r">

Possible solutions

Stick to Sphinx 7.3.7

Pro

• No extra work needed
• We directly see, when we generate new warnings of the type undefined label

Con

• Already old (Apr 19 2024), which might lead to problems in the future
• Locked in to current dependencies, which might need updates in the future

Upgrade to Sphinx 8.1.3 and ignore all undefined label:-warnings

Just add .*undefined label: .* to the regex-filter.

Pro

• Newest version including bugfixes
• no constraints in upgrading Sphinx or any of it dependencies

Con

• We won't see new warnings including undefined label: immediately