Backporting documentation to RTD

[consideRatio]

Background

We want to update documentation because of a security. But how do we backport documentation fixes to previous releases in our Read The Docs based website?

Backporting in jupyterhub/jupyterhub

I've seen that jupyterhub/jupyterhub is backporting code fixes in branches named 1.2.x 1.3.x etc, but that jupyterhub/jupyterhub still relies on the tags to publish different versions to RTD rather than branches.

Backporting docs (+ code) in Z2JH

Currently I think we need to backport documentation fixes by stop using RTD to feature tags, but instead feature branches.

How does RTD work?

• How dynamically can we declare what builds should be published as versions, and what decides the version presented to the user?
  • It would be great if we could name branches release/0.9 release/0.10 release/0.11 release/1.0 etc and then have RTD recognize "oh its a branch named release/... so we should present it on the website as a version named the same thing minus the release/ prefix" or similar.

[consideRatio]

Related documentation: https://docs.readthedocs.io/en/stable/versions.html

[consideRatio]

This is hard 😢

I went with the approach of declaring 0.9.x 0.10.x 0.11.x branches, but i fail to build the documentation because of updated versions of various packages to build the docs have made things break over time. I fail to build 0.9.x (0.9.0) but it works with 0.10.x (0.10.6) and 0.11.x (0.11.1).

Okay I've manually cherry-picked a commit fixing the build issues on 0.9.x, 0.10.x, and 0.11.x, and manually removed the insecure documentation step in those branches.

[consideRatio]

Done! It now looks like this on the published website.

@willingc what do you think? Does this make sense?

[consideRatio]

I'll go ahead and close this as resolved