idefix-code/idefix

DOC: use GitHub's dependabot to manage doc/python_requirements.txt ?

Opened this issue · 5 comments

neutrinoceros commented

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.

neutrinoceros commented

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

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 :

  • how much work (ie messing around with sphinx dependencies) these automatic PR will imply (there are quite a few hacks hidden in the doc generation since the api is documented through doxygen which is then parsed by sphinx)
  • how this is going to work with readthedocs (where the doc is actually published).

Do you have any experience on this?

neutrinoceros commented

Do you have any experience on this?

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.

But I'm not 100% sure to know :

  • how much work (ie messing around with sphinx dependencies) these automatic PR will imply (there are quite a few hacks hidden in the doc generation since the api is documented through doxygen which is then parsed by sphinx)

Hard to tell for sure before we give it a go but for what it's worth:

  • on the slowest schedule, dependabot allows for a single PR per month (it's still too frequent for my typical needs, but it is what it is)
  • as with all things, fixing small problems regularly might be a lot easier than solving a giant mess once in a blue moon (but I'm taking a bet here)
  • how this is going to work with readthedocs (where the doc is actually published).

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

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

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) !