Backport doc build changes for versioned docs

[jmeridth]

Summary

Keep track of doc build changes that need to be backported to prior versions so they can show as versioned docs on readthedocs.io (once #12360 merges)

Setup changes that need to be backported:

• .readthedocs.yaml
• Makefile
• mkdocs.yml
• hack/check-mkdocs.sh
• docs/requirements.txt

We'd still want the URL changes also from #12360 but instead of /latest/ suffix it'd be the semver (e.g., /release-[major].[minor]/ suffix)

• release-3.5 branch docs: update doc links to readthedocs/release-3.5 #12462
  • https://argo-workflows.readthedocs.io/en/release-3.5/ is live
• release-3.4 branch docs: update doc links to readthedocs/release-3.4 #12473
  • https://argo-workflows.readthedocs.io/en/release-3.4/ is live

---

Message from the maintainers:

Love this enhancement proposal? Give it a 👍. We prioritise the proposals with the most 👍.

[jmeridth]

@agilgur5 @terrytangyuan Working on the first PR for this. The files mentioned in the description above make sense and confirming those on my forked project in readthedocs but I also realized we need to update the 460+ files that still have github pages links in them. This brings up a few questions:

1. For backporting we need to switch to readthedocs links but do we, for the backports, want to change to https://argo-workflows.readthedocs.io/en/[version] (e.g., https://argo-workflows.readthedocs.io/en/v3.5.2) or have all backports point to latest (e.g., https://argo-workflows.readthedocs.io/en/latest)? I assume the version in the URL and we can point the version build in the readthedocs UI.
2. For the stable url we'll point it in the readthedocs URL at the latest stable version SHA. That's how it is done. You good with this? (as previously mentioned by @agilgur5 here)
3. How far back do we want to go?

• v3.5.2 - chore: backport documentation changes to v3.5.2 #12450
• v3.5.1
• v3.5.0
• v3.4.14
• v3.4.13
• v3.4.12
• v3.4.11
• v3.4.10
  etc
  OR (the latest of each minor version?)
• v3.5.2
• v3.4.14
• v3.3
• v3.2
  etc

[terrytangyuan]

v3.5.2 and v3.4.14 should be fine IMO

[terrytangyuan]

https://argo-workflows.readthedocs.io/en/[version] (e.g., https://argo-workflows.readthedocs.io/en/v3.5.2

This looks better

[jmeridth]

@terrytangyuan We will need to move the tag for each release to the HEAD of their perspective release-* branch.

Why? v3.5.2 tag is still pointed at old SHA that doesn't have the newly merged readthedocs configuration parts that is on HEAD of release-v3.5.2 branch.

Is this okay?

[agilgur5]

v3.5.2 and v3.4.14 should be fine IMO

yea I was only gonna do latest patch of each minor as well. 3.4 and 3.5 are most important ofc, the rest we can take our time with, no rush to get those out, can just do them whenever anyone has any free time / wants to take those on.

That's also what Argo CD currently has:

@terrytangyuan We will need to move the tag for each release to the HEAD of their perspective release-* branch.

I would suggest just changing the branch for the minor, i.e. release-3.5, to similarly match Argo CD: