chore: move documentation to readthedocs

[jmeridth]

Draft until I get the gh-pages PR updated with meta tags

Fixes #11390

Motivation

Moving to readthedocs so we can have versioned docs easily and standardize like argo-cd and other projects have already.

Modifications

• add .readthedocs.yml
• add docs/requirements.txt and use it in Makefile
• update urls in code
  • sdk and other files updates were from make pre-commit -B locally
• update .spelling with words to exlude during spellcheck
  • alphabetize
• update gh-pages branch with meta tags to handle redirects chore: Update GitHub pages to redirect to readthedocs #12362
• update /hack script to use new mkdocs built-in validation (example result here)
• remove the gh-pages publish action in this PR so that chore: Update GitHub pages to redirect to readthedocs #12362 isn't overwritten later

Verification

https://jm-argo-workflows.readthedocs.io/en/latest/

Notes

For us to have other versions available we have to mark them as Active in the readthedocs UI

But those versions have to have all of the changes in this PR or they will fail

So this idea of versioned docs may only apply going forward.

[jmeridth]

make test passes locally. Gotta research why the UI and Codegen tests are failing in CI.

[terrytangyuan]

-// Code generated by mockery v2.37.1. DO NOT EDIT.
+// Code generated by mockery v2.26.0. DO NOT EDIT.

The codegen failure is caused by an older version of mockery

[jmeridth]

-// Code generated by mockery v2.37.1. DO NOT EDIT.
+// Code generated by mockery v2.26.0. DO NOT EDIT.

The codegen failure is caused by an older version of mockery

Yep. Missed one. 😄 Fixed and pushed.

[Joibel]

Did you manage to work out why all the .spelling changes were needed? Or rather why they weren't needed before.

[jmeridth]

@Joibel no. My assumption, still needs verification, is that spelling was only validating modified files and due to the size of my changes, it included many files. I'm still trying to verify. The Makefile command docs-spellcheck isn't showing much to me except files to exclude.

[Joibel]

@Joibel no. My assumption, still needs verification, is that spelling was only validating modified files and due to the size of my changes, it included many files. I'm still trying to verify. The Makefile command docs-spellcheck isn't showing much to me except files to exclude.

The spelling check checks all files regardless of modification, but has some specific ignored files listed. One of your additions is Ansible which is only in docs/README.md which should be being ignored, so somehow I think your process which has caused you to add stuff to .spelling is bypassing the -not -name bits of mdspell.

I attempted to reproduce why you'd had to add them but failed:

$ git checkout jm-readthedocs
$ git checkout origin/main .spelling
$ mdspell --ignore-numbers --ignore-acronyms --en-us --no-suggestions --report $(find docs -name '*.md' -not -name upgrading.md -not -name README.md -not -name fields.md -not -name upgrading.md -not -name swagger.md -not -name executor_swagger.md -not -path '*/cli/*')
>> 131 files are free from spelling errors

I'm all for taking out some of the exclusions from the spelling checker, and making README.md and probably upgrading.md be spellchecked, it seems reasonable. Especially as upgrading.md is in the exclusion list twice. I'm not bothered if it goes in like it is - really just curious.

[agilgur5]

But those versions have to have all of the changes in this PR or they will fail

They need to have the build changes, but not necessarily all of the other changes.

So this idea of versioned docs may only apply going forward.

I think we should create a tracking issue for this and slowly backport changes for v3 at least. That was my plan to backport all docs fixes to older versioned docs as well. EDIT: See #12414

I'm all for taking out some of the exclusions from the spelling checker, and making README.md and probably upgrading.md be spellchecked, it seems reasonable.

One of the contributors from the OSS Academy this summer did try to get everything lintable (c.f. #11787 (comment)), but it wasn't quite completed

[agilgur5]

I still need to review the build changes (including the .spelling discrepancies pointed out above and in #12211 (comment)), but I reviewed all the content this look through, only a couple changes needed.

For other reviewers, note that the vast majority of this PR is automated changes to the SDKs which are one-liner comment changes to the new docs link. Can skip all the sdks/ paths as such

[agilgur5]

We also need to remove the gh-pages publish action in this PR so that #12362 isn't overwritten later

[terrytangyuan]

LGTM

[jmeridth]

It's alive. https://argo-workflows.readthedocs.io/en/latest/

Resyncing #12362 now and will open for merging.

[agilgur5]

Only thing I'm wondering about is if giscus will end up creating new GH Discussions for the new URLs and each version of the URLs? I don't think giscus is a huge deal either way, but I am wondering how that will work out

Giscus is indeed creating new URLs now, and seemingly for each version too 😕 See #12451 as an example of the first Giscus discussion created on RTD.

I wonder if we can configure Giscus to use existing discussions or at least use the same name/version for all new ones instead of different ones per version. It currently seems to naively use the full URL path

[agilgur5]

Investigated Giscus, can see the mkdocs-material docs and the Giscus docs/setup, which is integrated on this line of code.

Unfortunately, Giscus can only use the full pathname, the full URL, the full title, or a hash, so it won't be able to match the old page discussions out-of-the-box.

That being said, Giscus performs a search on the GH Discussions to match a page to a discussion, so we can modify the old discussions to have the new URLs in them, which should make the search work.

Main problem with that is, well, I don't have permissions to edit Discussion titles or opening comments, as that's only granted with write permissions (c.f. argoproj/argoproj#243).

If someone can grant me those permissions temporarily, I can manually edit all the existing page discussions to match up

[agilgur5]

That being said, Giscus performs a search on the GH Discussions to match a page to a discussion, so we can modify the old discussions to have the new URLs in them, which should make the search work.

Main problem with that is, well, I don't have permissions to edit Discussion titles or opening comments, as that's only granted with write permissions (c.f. argoproj/argoproj#243).

As I now have permissions (argoproj/argoproj#277), I did do this for a few discussions, but ran into a couple of issues:

1. When a discussion is edited, it moves to the front page of the discussion as it was "recently updated"
2. There are like 100 Giscus discussions. That's a lot to manually go through (although I could possibly write a script that uses the GH API for it), and editing all of them will clog up like 5 pages of discussions, per above

Given that Giscus discussions are also not necessarily made for Q&A, as there are multiple Q&As in one, no "mark as answer" possible, and not easy to search since there can be dozens of comments, I am considering removing Giscus entirely. It is a source of interactivity for new users, but I don't think a very efficient one for getting questions answered. Pointing to people to search issues and discussions and open a new one if they don't see an answer would be more optimal, but not necessarily that simple UX-wise

[agilgur5]

Given that Giscus discussions are also not necessarily made for Q&A, as there are multiple Q&As in one, no "mark as answer" possible, and not easy to search since there can be dozens of comments, I am considering removing Giscus entirely. It is a source of interactivity for new users, but I don't think a very efficient one for getting questions answered. Pointing to people to search issues and discussions and open a new one if they don't see an answer would be more optimal, but not necessarily that simple UX-wise

PR to remove Giscus and replace with links to search Discussions and Slack: #13138