Docs don't build using sphinx version in reqirements
mondus opened this issue · 4 comments
At least not in Python 3.10. See sphinx-doc/sphinx#9562
Can fix by enforcing newer Sphinx version. E.g. 5.x
Sphinx >= 4.2.0 should be fine according to the referenced issue.
However, our requirements.txt currently limits sphinx to be < 4.1.0 due to breahte/exhale PRs (referneced in requirements.txt). These have been merged, so increasing breathe to >= 4.31 would also be required if I've correctly understood the release / PR timelines.
This will need some testing.
Probably worth expanding our docs build CI to test min/max supported python versions too (3.7 and 3.10 currently? 3.11 soon?) to catch these issues (maybe a latest python would be nice, not sure how feasible this is without a lot of effort.
Breathe added support for Sphinx 5.0 in the latest release (4.34.0, 2022-06-20).
None of the breaking sphinx 5.0 changes look like they should impact us at a glance.
Exhale >= 0.3.2 requires pyhton >= 3.7 (i.e. dropping 3.6), but otherwise doesn't seem to require specific breathe / sphinx versions / conflicts (atleast based on its change log).
Moving to Sphinx >= 5.0 and Breateh >= 4.34 plus updating CI to use python 3.7 and 3.11 seems like it should be fine and will pull in a number of fixes.
I have tested on Sphinx 5.0 and all seems fine.
This should actually be Breathe >= 4.31 but bumping to 4.34 is no issue.