Azure pipelines to deploy docs

[wkerzendorf]

We are switching from TRAVIS to azure and so it would be nice to use the amazing doctr tool as well. I guess this is similar to #345 . it currently seems to crash with --force as it requires the environmental variables from TRAVIS (which we can set - but it would be nice if that was fixed).

[asmeurer]

Agreed. It won't just work out of the box, because you have to somehow create a deploy key for your gh-pages repo and either put it on Azure or encrypt it for Azure. For Travis, each repo has an encryption key we use to encrypt it that can only be decrypted in the Travis build. For Azure, it would be something different.

It would actually be nice if Azure supported pushing to gh-pages natively. I'm guessing it has better direct support for managing SSH keys than Travis. That is, if we can just upload an SSH key directly and have it be present in the build, that would simplify what doctr does a lot.

[gforsyth]

Seems like there's an undocumented API for uploading to a pipeline's "secure files" where we could just drop an SSH key: microsoft/azure-pipelines-tasks#9172 (comment)

[asmeurer]

So it seems that Azure (as well as GitLab), in order to authenticate for the configure stuff, requires you to register as an oauth application, and the open a webpage, which then does a callback to your URL. So I think to make it work we would have to first register as an application, open the login webpage, then use a simple flask server to receive the callback from the login page. I played with this a bit and wasn't able to get it working properly with gitlab. Here is an example of the same sort of thing with the reddit API https://gist.github.com/kemitche/9749639.

Probably for a simpler first go, we should just point people to the UI page where they can paste the appropriate thing to create the secure environment variable. It kind of sucks if we need to save the private SSH key to a file and/or print it to the terminal, so we should try to get a real login flow working.