Repository navigation
DOC: use GitHub's dependabot to manage doc/python_requirements.txt ? #191
Description
Question
While it's good practice to pin down exact requirements for documentation builds in a requirement file (as we do now), in my experience this tends to not be future-proof as indirect dependencies release incompatible versions and break builds.
A common solution is to use GitHub's dependabot service to periodically issue update PRs so the requirements do not rot away into inevitable breakage.
This would also necessitate integrating test builds into the CI.
I'm happy to do all of that when I'm back from vacation.
Activity
neutrinoceros commented on Oct 12, 2024
Hey, I'm back from vacation !
another solution would be to pin the entire environment, including indirect dependencies. Still not 100% future proof (it could reduce portability or make it harder to upgrade to a newer Python), but it's a pretty cheap one-time cost.
I'm game to do it that way too.
How about it, @glesur ?
glesur commented on Oct 12, 2024
A long-standing issue...! I think the best solution is actually the first one, as it allows us to follow the inevitable evolution of python and sphinx packages. But I'm not 100% sure to know :
Do you have any experience on this?
neutrinoceros commented on Oct 13, 2024
I do ! This is a widely spread strategy for keeping Python requirement files updated and I've used it on many projects big and small.
Hard to tell for sure before we give it a go but for what it's worth:
this part is actually trivial, dare I say already solved: readthedocs uses this requirement file already
https://github.com/idefix-code/idefix/blame/2f15373cb58387d67a91bd1e289416aab4813657/.readthedocs.yaml#L29
(or maybe I'm missing the point ?)
glesur commented on Oct 14, 2024
My point is that readthedocs might just break silently, since the build success (or not) of the doc by readthedocs is not a CI.
We can give it a go...
neutrinoceros commented on Oct 14, 2024
It should be possible to configure readthedocs to build in CI specifically when this file is updated. If not, it should be easy (albeit a bit wasteful) to add a custom GitHub Action job that mimicks it.
I'll look it up (sometimes soon) !