Enable Read the Docs generation on Pull Requests

[EwoutH]

Read the Docs allows you to generate docs for PRs, so that you immediately can check if your code and docs changes processed right. This makes validating and reviewing PRs that include docs changes easier.

See https://docs.readthedocs.io/en/stable/config-file/v2.html

[EwoutH]

See this link for more details: Preview Documentation from Pull Requests

[rht]

@jackiekazil ^

[EwoutH]

@jackiekazil Could you take a look at this? Enabling Read the Docs on PRs will help review PRs, like #1481.

[jackiekazil]

Yes! I will take a look tomorrow.
Thank you for the ping. sometimes I miss messages.

[EwoutH]

@jackiekazil Friendly reminder :)

It should be a few clicks in 2 minutes, following these steps:

1. Go to your project dashboard
2. Go to Admin, then Advanced settings
3. Enable the Build pull requests for this project option
4. Click on Save

It really helps reviewing pull requests with documentation changes!

[jackiekazil]

@EwoutH you are the best. Sometimes I get so many emails that these fall thru the cracks. I need a better way to filter my github notifications.

Now for the sad part -- it was already checked in readthedocs -- so either someone else changed it or it is not working in some way. Thoughts on running a test to trigger it?

[EwoutH]

@jackiekazil No worries! :) My system is just to log in on GitHub once and a while, and check the unread notifications.

Now for the sad part -- it was already checked in readthedocs -- so either someone else changed it or it is not working in some way. Thoughts on running a test to trigger it?

That's strange. Can you try the steps in the Troubleshooting section?

[jackiekazil]

I don't know that a build hasn't happened since the box was checked, because I don't know when/who checked the box. 
Is there a PR to test it with?

[EwoutH]

It should have ran on PRs like #1517 and #1510.

The easiest way would be to open a draft PR (with a minor whitespace change or something) and push it every time you change a setting.

Otherwise maybe we can debug it during a screen sharing session. Does @tpike3 have Read the Docs admin rights? In that case we can maybe fix it in our meeting in a minute.

[EwoutH]

@jackiekazil Maybe we can do a quick screensharing session to figure it out together?

If you like that, I'm available Tuesday and Wednesday between 10 and 16 UTC.

[jackiekazil]

@EwoutH I was just looking at webhook...
The last trigger was this commit -- 9dbffeb54e

What are you expecting to see that you don't see? It looks like it is being triggered to me.

[EwoutH]

@jackiekazil It looks like that’s all on the main branch, not on pull requests. It should also run when a pull request is opened or modified, to see how the pull request affects the docs.

In the checks part of a pull request the Read the Docs build should also show up. Here an example from another repo:

[jackiekazil]

I created this #1525 just to test it. Can you confirm that is how it is intended to work?

[EwoutH]

Awesome, it now works as intended!

[Corvince]

Really cool this is finally working.

Previously we also had the doc_build branch that always triggered a rebuild of the documentation. But of course this approach is much better so I went and removed the doc_build branch from RTD.

Being at it I also restructered the active and visible branches (that you can select from the slide-out menu). Previously we had latest, main, doc_build. (where latest and main were both pointing to the main branch). Now I have activated stable, latest and made stable the default document. Stable understands semantiv versioning and always points to the latest release. Latest still points to our main branch.

I hope this is fine with everyone. I am closing this now, but please reopen if someone thinks this should be differently.

[wang-boyu]

Would probably need to update the README files etc? Previously they were pointing to the main build if I remember correctly.

[Corvince]

Good catch! I reactivated main for now

[EwoutH]

@wang-boyu @tpike3 could we enable Readthedocs pull request builds for Mesa-geo? That would make reviewing PRs like projectmesa/mesa-geo#217 easier.

• https://docs.readthedocs.io/en/stable/guides/pull-requests.html