Fix: pin breathe to <5 due to potential name conflicts

[mgovers]

The C API docs have been broken since v1.13.179 (#1612) because Breathe had a major version bump that seems to be incompatible with our setup.

The docs build will raise a warning (we don't have warnings-as-errors enabled yet in our readthedocs build) and the docs will have the following warning

This seems to be caused by the fact that breathe 5 uses the Doxygen-generated shortname, which is the shortest unique name that matches a file. For files with a unique name (e.g., basics.h), that is simply the file name.

However, this is not future compatible, as adding a new file with the same name in another directory will cause the Doxygen-generated shortname to change to a path, e.g. power_grid_model_c/basics.h ad foo/basics.h, effectively breaking the internal linkage if we depend purely on the short name basics.h. Therefore, the docs will not be stable under addition of new files, which is bound to happen.

• This is probably not directly a problem for the C API (as they .h ending is most likely restricted to just the C API headers)
• However, this is already an issue for locally generated docs for the C++ API, which may contain names that occur in both the C++ API and in the core (e.g., model.hpp).
• For now, readthedocs builds are unaffected, as we do not formally expose the C++ API docs there yet, but if we decide to do so in the future, this will become a real problem.

Related

Underlying issue reported to Breathe in breathe-doc/breathe#1084

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[figueroa1395]

Docs build successfully now.