Test docs using ReadTheDocs CI instead of GitHub Actions

[adamjstewart]

ReadTheDocs has its own CI platform. We should use this instead of GitHub Actions for the following reasons:

• Identical environment as the one where the docs are actually hosted
• Better control over Python version used during testing (Declare Python 3.7+ support #212)
• Able to preview docs for a PR before it is merged

This PR updates .readthedocs.yaml to the latest API and sets fail_on_warning: true so we can catch documentation issues before a PR is merged. However, to get ReadTheDocs CI set up, someone with admin privileges will need to configure a few additional things. @hobu can you follow the instructions at https://docs.readthedocs.io/en/stable/pull-requests.html and see if that works?

@mwtoews may also be interested in this.

[mwtoews]

Looks good to me, but obviously it would be nice to see the rendered output.

[adamjstewart]

Yep, once @hobu sets things up on the RtD side we'll be able to see the rendered output directly in this PR by clicking the "Details" link on the CI check.

[hobu]

https://readthedocs.org/projects/rtree/

[hobu]

It looks like @sgillies is the admin of note here, so he'll have to update that in RTD as suggested or add me as an admin

[hobu]

@sgillies made me an RTD admin, and I have enabled PR builds, so once this conflict is resolved, things should be working.

[adamjstewart]

Rebased but I'm still not seeing a RtD check being added. Maybe try the suggestions in https://docs.readthedocs.io/en/stable/pull-requests.html#troubleshooting?

[hobu]

OAuth 👯‍♂️ done. Please try again.

[adamjstewart]

Still not seeing it. Maybe tweak the settings for your webhook? https://docs.readthedocs.io/en/stable/integrations.html#github

[hobu]

looking like stuff is connected.

[adamjstewart]

On the GitHub side, for Spack and TorchGeo (two projects where we use RtD CI), under "Which events would you like to trigger this webhook?", we have the following events selected:

• Branch or tag creation
• Branch of tag deletion
• Pull requests
• Pushes

We also have "Active" checked at the bottom. If one of these isn't the problem for this repo then I'm not sure what else it could be.

[adamjstewart]

Might be worth reaching out to support@readthedocs.org, they got back to me pretty quickly last time.

[hobu]

Even easier to give you admin 😄

[adamjstewart]

Just took a look. The only other thing I see different is that we're using application/x-www-form-urlencoded instead of application/json. Let me try that.

[adamjstewart]

Yeah, I'm out of ideas. Probably best to reach out to RtD support.

[mwtoews]

Perhaps this PR may need to be merged before taking effect.

[adamjstewart]

I don't think that's the case, but I could be wrong. Certainly no harm in merging this first.

[adamjstewart]

I'm trying to set this up for another repo I maintain and I'm running into issues with that one too. I'm going to email RtD support, I'll let you know what they say.

[adamjstewart]

Okay, I got this working for another repo that I maintain. The "fix" was to log in to ReadTheDocs, go to my account settings, go to "Connected Services", and then disconnect and reconnect to GitHub. Unfortunately, this didn't solve the issue for rtree, possibly because I'm not the primary maintainer? Maybe @sgillies (or even @hobu) can try this?

[hobu]

ok, I bounced my github token again with RTD, but IIRC, I tried that when I was chicken waving the last iteration without success. It might be that @sgillies has to be the one to do it.