acts-project / acts-project/acts

docs: Sphinx `>=7.4.0` breaks warning ignore script

Abierto
#3,879 1 comentario 0 reacciones 0 asignados Ver en GitHub
Component - Documentation Needs Decision Stale
Lenguaje dominante
C++
Estrellas
131
Forks
276
Merge medio
3 d 13 h
PR fusionados (30 d)
112

Descripción

# 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`
```




```

### Handled object since `7.4.0`
```

```

# 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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.