chore: backport documentation changes to v3.5.2

[jmeridth]

Motivation

relates to #12414

Modifications

• move over files to help with readthedocs build
  • .readthedocs.yaml
  • Makefile
  • mkdocs.yml
  • hack/check-mkdocs.sh
  • docs/requirements.txt
• change links from github pages to readthedocs v3.5.2

Verification

[terrytangyuan]

LGTM

[jmeridth]

@terrytangyuan will we move the tag for v3.5.2 to this new SHA (aka HEAD of release-3.5.2 branch)?

[terrytangyuan]

I don't think that's possible

[terrytangyuan]

We should only create new tags instead of modifying existing ones

[agilgur5]

I've mentioned this before, but ideally we should use a versioned branch that we can make tags off of.

For instance, we could have 3.5.x and any backports and patches would target that. We could also use that branch for the docs (unless RTD doesn't support that?)

I don't think that's possible
We should only create new tags instead of modifying existing ones

It is possible, though generally not preferred. This is one of those edge cases where changing it does make sense though. Otherwise, we can tag release-3.5.2-docs or something. A 3.5.x branch is probably optimal if RTD supports it

[agilgur5]

Ah looks like Argo CD has the release-3.5 -style branch for each minor that I think it would make sense for us to use as well. See my comment in #12414 (comment) for screenshots/examples of that

[agilgur5]

Ah I see, these changes will impact people who navigate to the release-3.5 branch directly for the examples and docs.

The source code changes would only affect the next version of the binary though, which would be v3.5.3 at that time. Hmmm... using release-3.5 or 3.5.x for the version number in the docs permalink may make the most sense then

[terrytangyuan]

We do have those release branches. The problem is modifying an existing tag.

[terrytangyuan]

See https://github.com/argoproj/argo-workflows/branches/all?query=release

[agilgur5]

See https://github.com/argoproj/argo-workflows/branches/all?query=release

It looks like we're currently using release-3.5 as tracking v3.5.0 specifically though (the .0 patch as in), as opposed to the minor as a whole, since it is behind release-3.5.2.
If we use the branch in RTD instead of a tag, then I think we should cover most of the bases

[terrytangyuan]

Can we use a branch? Then it is as simple as syncing release-3.5 branch to be up-to-date with 3.5.2

[agilgur5]

Looks like we can indeed use a branch:

[jmeridth]

Yes we can use a branch but I need to issue another PR to change the URL to /release-3.5.2 instead of /v3.5.2. Why can't we move the tag? I'm not understanding that. Shouldn't the tag point to the head of its release branch?

[jmeridth]

Nm. I see @agilgur5's comment here. We should match ArgoCD

[agilgur5]

Why can't we move the tag? I'm not understanding that.

A tag is supposed to be a stable reference, as opposed to a branch. Some artifact registries don't allow changing tags either (like NPM, for instance).
Git/Go and Docker/OCI registries actually have mutable references however, which is why using a SHA or digest in addition to the version number is a general recommendation for supply chain security purposes for those registries (see also #12031 "Pinned Dependencies").

But for most intents, you typically want tags to be immutable.
This is an edge case where I'd support moving it, although as we're not making a new GH release of the binary etc, I'd rather keep things consistent where possible. And if we're just doing the minor branch then we can leave the tag as immutable.

The branch won't cover all the bases (i.e. old versions of the binary and old release tags will still point to GH Pages), but it'll cover all the most important ones, which is "good enough" IMO. Everything else will get redirected to latest, which matches the previous behavior anyway

[agilgur5]

Follow-up PR in #12460