add building of test documentation of RTD

[basnijholt]

This builds the documentation for each branch on https://adaptive.readthedocs.io/en/test_documentation

Todo:

• need to check if the build is for the correct Git commit hash here.

[basnijholt]

This seems to work, @akhmerov, what do you think?

[akhmerov]

First of all, this is at best a temporary solution because of the following reasons:

• The test_documentation branch shows on rtd, which may confuse the users.
• This approach of having one such branch won't work as soon as there's more than one active PR

But even with that in mind, I still don't understand whether this satisfactory. My main question is: what will happen if a user that isn't a team member opens a PR? I can imagine several different possible outcomes:

• The pipeline doesn't run at all
• The pipeline runs, but fails because the push fails
• The pipeline runs and force-pushes to the branch test_documentation in the fork
• The pipeline runs and force-pushes to the main repository.

In order to come to a decision on this PR I would like to know for sure which of these options is realized. Is there a document that describes the permissions model of azure pipelines with forks?

[jbweston]

I agree with @akhmerov that to merge this we would need to:

• know what happens when someone opens a PR from their fork of adaptive
• allow multiple PRs to be open at the same time without each clobbering the other's docs deployment
• somehow hide all these "test" builds in readthedocs so that it's not confusing for users.

[basnijholt]

@akhmerov and @jbweston, I've opened #262 with a different account to see what happens.

As I expected, no other person will be able to force push to our repo.

Therefore, building the docs will only work for the core maintainers, and since nearly all of the PRs that have ever been made come from us, I believe that that's fine.

I don't think your other point trump the fact that right now we do not have any tests.

Right now, the docs are also broken and it's terrible to debug.

I say, let's merge this as it is!

[akhmerov]

It seems that since the initial implementation, rtd has enabled documentation building for PRs: https://blog.readthedocs.com/building-docs-for-pull-requests/, @basnijholt what do you think?

[basnijholt]

@akhmerov, I've requested the feature and we've got it!

See for example https://adaptive--263.org.readthedocs.build/en/263/