Testing readthedocs' pr integration (do not merge)

[fgaz]

No description provided.

[fgaz]

@Mikolaj it works \o/

https://readthedocs.org/projects/cabal/builds/14708732/

https://cabal--7647.org.readthedocs.build/en/7647/

and it's super fast too

[Mikolaj]

Yay! How do we wire it into CI? Or do we keep the new CI docs check in CI and use this one only for people that want to see the actual results of doc changes? Does it email somebody when it fails or just show a broken page?

[fgaz]

We could mark it as required and remove the github actions one. Before that we'd have to reflect the flags from the makefile to readthedocs, eg. https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx-fail-on-warning

Does it email somebody when it fails or just show a broken page?

it shows a failed check in the CI section like github actions (it's hidden now since I closed the pr, but you can see it by clicking the red X on the commit)

[Mikolaj]

Got it. That's great news. Let's keep them both until we are sure they work consistently and the check by @andreasabel is completely subsumed by the ultimate check using Read The Docs.

[Mikolaj]

Or does #7638 introduce more/stricter checks and they can't be ported to readthedocs server proper? Or can/should it introduce stricter checks? Is it worth keeping another CI job?

[fgaz]

I don't know yet, I didn't check in depth

[andreasabel]

@fgaz You could try to run it on a PR that broke links in the docs, e.g., #7498.
To prevent doc formatting issues (broken links etc.) I think there should be a CI check that fails in that case.

[andreasabel]

This conversation ends abruptly. The ReadTheDocs CI seems to be running, see https://readthedocs.org/projects/cabal/builds/15099302/, but where is it documented, like:

• how to switch it on/off
• how to maintain
• why is it showing up in the list of checks in a PR, but not here: https://github.com/haskell/cabal/actions

Please add pointers here.

[fgaz]

how to switch it on/off
how to maintain

like all jobs, its settings are managed upstream (in this case here and in .readthedocs.yml) and it can be marked as required in the repo settings

why is it showing up in the list of checks in a PR, but not here: https://github.com/haskell/cabal/actions

only github actions show up in that page

[Mikolaj]

I think, given the current breakage of the readthedocs CI job, the importance of having a local docs test is underlined. In addition, it has stricter settings and just a slightly different angle and context. Also, it runs only when /doc/ changes, so is very cheap compared to the readthedocs job. I'm in favour of having both.