chore: replace gh-pages output with index.html redirect

[jmeridth]

Relates to #12211

Motivation

Clear gh-pages and setup redirect to ReadTheDocs so users can easily find the new versioned docs

Modifications

• setup redirect to readthedocs

Verification

[jmeridth]

I'm up for an auto-redirect solution also (javascript or .htaccess). This solution is SEO friendly but not automated. wdyt?

[tico24]

Although "ugh", this is probably the nicer way to do things for the long term rather than throwing an automated solution in.

[agilgur5]

I'm up for an auto-redirect solution also (javascript or .htaccess). This solution is SEO friendly but not automated. wdyt?

If I'm reading the changes correctly, this change just makes all GH pages 404 and redirect to one page, RTD index page? As in, they do not redirect to their equivalent page in RTD?

Per my comment in the original issue, redirects are incredibly important, especially for docs, as they should be reliable (semi-)permalinks. Otherwise I would reference versioned permalinks of the raw markdown on GitHub.

Breaking all existing docs links is simply not an option in my book and is a very, very bad UX that nullifies any benefits of a change. Heck, part of the reason we're adding versioning is so that specific versions of the docs can be linked to; improving version linking while breaking all old links runs counter to the underlying UX purpose of that change. Breaking links is an anti-pattern.

The last 6+ years of docs links will just no longer be useful. Any links in people's codebases, internal docs, and even contributors' own links in PRs, commits, issues, discussions, and Slack would immediately lose their value. This is even more important given the scope of Argo's docs -- it happens very often that a user simply couldn't find the feature. The quick link that got them to the right place and can be used by all future readers would no longer be helpful.
Docs are a knowledge base; breaking links to your knowledge base means breaking part of your knowledge.

We should have proper back-end redirects for all the current docs pages.

Although "ugh", this is probably the nicer way to do things for the long term rather than throwing an automated solution in.

Redirects are one-offs. Once we create all the redirects of the existing docs pages, we would not add any more. New links would only be added to RTD

[Joibel]

lionello/lionello.github.io@c175f65 shows a way of doing a 404 style redirect which honors the original path. This isn't exactly what @agilgur5 is after, as it will work for currently non-existent pages, but is probably a decent workaround rather than having hundreds of individual redirects.

[terrytangyuan]

We need to make sure redirects would work.

[agilgur5]

This isn't exactly what @agilgur5 is after

It's also not a proper back-end redirect. That's the front-end sending you to a new URL, which has different semantics than a redirect (in a handful of ways).
The meta elements attempt to replicate the semantics, and so are closer. They also make more sense for SEO.

We would also want some styling and a message on screen for users (including the standard "click this link if you are not redirected automatically") for the best UX, as the page will be at least temporarily visible.

but is probably a decent workaround rather than having hundreds of individual redirects.

They will all be identical pages except for the link itself, so I do think we can generate those fairly straightforwardly once we have a good base page.
This is a one-time effort, and so I think it is well worth the extra effort given the 6+ years of links that will be permanently impacted.

[jmeridth]

@agilgur5 @terrytangyuan I agree the redirects are absolutely required. Going to try the GitHub pages external-sites.json file and see if that results in what we want. It will most likely result in meta tags and that helps SEO, like @agilgur5 said, but isn't a backend redirect. Will test.

[jmeridth]

Will fix conflicts also

[agilgur5]

Going to try the GitHub pages external-sites.json file and see if that results in what we want.

Oh that's not for GH Pages, that's for the GH Docs themselves (which have been open-source the past few years). Their own contributing docs are also hosted on GH's Docs, which is a little confusing. It pops up on some searches for GH Pages things unfortunately, which does not help

[jmeridth]

Closing temporarily to prevent workflows from firing. Testing in my fork. Will reopen once satisfied.

[agilgur5]

Replaced by #12362