Update RTD config

[glatterf42]

Superseded by #485

As noted by Xiaoyang on Slack, it's not intuitive to choose [tests] as the extra requirement for building the docs when we also have [docs]. This PR replaces the selection hoping it works out of the box. In the same process, it renames the config file to comply with current recommendations.

How to review

• Read the diff and note that the CI checks all pass.
• Build the documentation and check that it works as usual.

PR checklist

• Continuous integration checks all ✅
  Except for macos-latest-py3.7 per Track/work around actions/setup-python#682 #484.

[codecov]

Codecov Report

Merging #483 (8a680d1) into main (f348a6b) will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##            main    #483   +/-   ##
=====================================
  Coverage   98.5%   98.5%           
=====================================
  Files         42      42           
  Lines       4489    4489           
=====================================
  Hits        4425    4425           
  Misses        64      64           

[glatterf42]

As per the instructions for checking the RTD build locally, the command completed successfully. We might still be missing some packages required for building the docs by only requiring the extra [docs], but I'm not sure how to test that since the PR originates from my fork (so we cannot simply enable builds for this branch on RTD itself).

[khaeru]

We might still be missing some packages required for building the docs by only requiring the extra [docs], but I'm not sure how to test that since the PR originates from my fork (so we cannot simply enable builds for this branch on RTD itself).

RTD did not originally support building docs for PRs, but has recently added this feature: https://docs.readthedocs.io/en/latest/guides/pull-requests.html. We could turn this on, but should first consider security implications, which I haven't had time to do. (For example: code examples in the documentation or code in Sphinx conf.py can be run while the Sphinx build occurs. Could a user abuse this to, e.g. attempt to DDoS our or someone else's public-facing servers?)

So some options would be:

1. Cautiously or temporarily (just for this PR) enable that.
2. Re-open the PR with the same commit pushed to a branch in the main repo.

If (2), then see #484 (comment) and the comment linked from there.

[glatterf42]

From these options, I would choose 2 since I don't know how to assess DDoS potential. However, I'm not sure what I can gain from the linked comment: do you suggest to merge a PR with the suggested changes before opening a new one here?

[khaeru]

However, I'm not sure what I can gain from the linked comment: do you suggest to merge a PR with the suggested changes before opening a new one here?

I meant that, if/when you push to a new branch in the main repo and open a new PR, it could be convenient to add 1 more commit adding the 1 suggested line, at the same time.

[glatterf42]

Superseded by #485