Trigger automatic build of readthedocs

[lmohrmann]

I'm almost sure I've brought up this issue previously, but couldn't find it in any of the existing issues.

We're using readthedocs to build a publicly accessible documentation for the GADF format. Currently, a manually triggered re-build of the docs is required after each merged PR, to update the readthedocs page. This needs to be done by one of the maintainers of the gamma-astro-data-formats project on readthedocs - of the still active people, I think that currently includes only @TarekHC and myself.

It would be very much preferable to trigger automatically new builds on readthedocs when PRs are merged. I've tried to set this up at some point in the past, but failed. If anyone has experience with this kind of thing (@maxnoe?), then help would be much appreciated!

We can also think about adding more people as maintainers of the readthedocs project - thoughts on this would be welcome as well.

[maxnoe]

I never used readthedocs, I just used the sphinx integration to push the output to github pages. However looking at their documentation it should be easy to setup, basically just importing the project and switching on some options.

Tags should be converted to versions that can be (probably still manually) configured to appear.

Do we really want to trigger the RTB build after each merged PR? Or just for released versions? The dev version is available on github pages: https://open-gamma-ray-astro.github.io/gamma-astro-data-formats/

and that is automatically build after each PR.

[lmohrmann]

Good question - opinions welcome! I would argue that the dev version is what people mostly look at these days - the latest release v0.2 is pretty old already. And it could certainly cause some confusion if the readthedocs page and the one on github pages are out of synch, don't you think so?

[cboisson]

it is confusing indeed - they need to be synchronized

[maxnoe]

it is confusing indeed - they need to be synchronized

If they are synchronised, there is no reason to have both. Just checking, I was surprised to see that there is also an old version of the dev release on readthedocs. That is indeed confusing.

Good question - opinions welcome! I would argue that the dev version is what people mostly look at these days - the latest release v0.2 is pretty old already.

Yes, but it's the only release supported by science tools. So users looking how to produce files should check the docs for 0.2, since that is what gammapy and ctools can handle.

I see two options then

• only using readthedocs and making sure that the dev version is always up-to-date
• only publishing released versions on readthedocs (removing dev) and put the dev version on github pages.

I don't have a strong opinon, but you are right that the current situation is confusing.

[maxnoe]

@lmohrmann Maybe we can have a zoom meeting to see if we can get the readthedocs autodeploy to work?

[lmohrmann]

I think I would prefer the first option on your list, but I don't have very strong feelings. This would require that we manage to set up automatic builds on readthedocs, though.

I triggered a manual build of the dev version on readthedocs a few minutes ago by the way, so it should be up-to-date now.

[lmohrmann]

@lmohrmann Maybe we can have a zoom meeting to see if we can get the readthedocs autodeploy to work?

Sure, that sounds good. Today is not a good day for me, but next week should work - let's coordinate via the Gammapy Slack to find a good date!

[TarekHC]

Hi all,

I agree the current situation does not make sense, and I I may also be inclined to support the first option.

Unfortunately I'm not very useful to technically fix the issue. But if you need me, I will also be available next week depending on the time.

[maxnoe]

The automatic building works again, I needed to adapt the URL for the RTD webhook in the repository settings here on github to the link generated by RTD in the "Integrations" settings.

We disabled the github pages build here: #189

I also installed a redirect to the RTD page into the github pages branch, so if you visit

https://open-gamma-ray-astro.github.io/gamma-astro-data-formats you will be redirected to RTD

[lmohrmann]

Thanks @maxnoe ! 👍