chore: move documentation to readthedocs

Yes. I'm aware of the size of this change. I cringed also. One must hunt down all URLs and change them. 😄 Fixes argoproj#11390 ### Motivation Moving to readthedocs so we can have versioned docs easily and standardize like argo-cd and other projects have already. ### Modifications - [x] add .readthedocs.yml - [x] add docs/requirements.txt and use it in Makefile - [x] drop gh-pages publish step in docs GitHub action - [x] update urls in code - [x] sdk and other files updates were from `make pre-commit -B` locally - [x] update .spelling with words to exlude during spellcheck - [x] alphabetize - [x] update gh-pages branch with meta tags to handle redirects argoproj#12212 - [x] update /hack script to use new mkdocs built-in validation (example result [here](https://github.com/argoproj/argo-workflows/actions/runs/7210935020/job/19645182282?pr=12360#step:6:148)) Signed-off-by: jmeridth <jmeridth@gmail.com> Co-authored-by: Tim Collins <tim@thecollins.team> Co-authored-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
jmeridth · Dec 27, 2023 · 70fe7ac · 70fe7ac
1 parent dbf4215
commit 70fe7ac
Show file tree

Hide file tree

Showing 468 changed files with 559 additions and 531 deletions.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -2,7 +2,7 @@ blank_issues_enabled: false
 
 contact_links:
   - name: Have you read the docs?
-    url: https://argoproj.github.io/argo-workflows/
+    url: https://argo-workflows.readthedocs.io/en/stable/
     about: Much help can be found in the docs
   - name: Ask a question
     url: https://github.com/argoproj/argo-workflows/discussions/new

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -12,9 +12,6 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-permissions:
-  contents: read
-
 jobs:
   docs:
     runs-on: ubuntu-latest
@@ -44,10 +41,3 @@ jobs:
           name: docs
           path: site
           if-no-files-found: error
-      - name: Publish to GH Pages (when on main)
-        if: github.repository == 'argoproj/argo-workflows' && github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_branch: gh-pages
-          publish_dir: ./site
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,11 @@
+version: 2
+formats: all
+mkdocs:
+  fail_on_warning: false
+python:
+  install:
+    - requirements: docs/requirements.txt
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.12"
diff --git a/.spelling b/.spelling
@@ -30,9 +30,11 @@
 Alexandre
 Alibaba
 Ang
+Ansible
 Anthos
 ArgoLabs
 Artifactory
+Beda
 BlackRock
 Breitgand
 Codespaces
@@ -42,13 +44,18 @@ ClusterRoleBinding
 CRD
 CRDs
 CloudSQL
+CronWorkflow
+CronWorkflows
 DataDog
 Dataflow
+Devenv
 DevOps
 Dex
+DinD
 EditorConfig
 EtcD
 EventRouter
+Generator
 GitOps
 Github
 Golang
@@ -68,16 +75,21 @@ IPs
 Jemison
 JetBrains
 KNative
+K8s
 Kaniko
 Katacoda
+Katib
+Kedro
 Kerberos
 Killercoda
 KubectlExec
 Kubeflow
 Kustomize
+LDFlags
 Lifecycle-Hook
 LitmusChaos
-metadata
+Makefile
+Metaflow
 MLOps
 MinIO
 Minikube
@@ -89,24 +101,34 @@ Node.JS.
 OAuth
 OAuth2
 Okta
-parameterizing
+Onepanel
+OpenShift
+OpenStreetMap
+Orchest
+Parameterization
 PDBs
 PProf
 PVCs
 Peixuan
 Ploomber
 Postgres
+Polyaxon
+Quickstart
 RCs
 Roadmap
 RoleBinding
+Rollouts
 s3
 SageMaker
 SDKs
+SECURITY.md
+Seldon
 ServiceAccount
 Sharding
 shortcodes
 Singer.io
 Snyk
+SQLFlow
 Sumit
 Tekton
 Traefik
@@ -132,6 +154,9 @@ config
 cpu
 cron
 daemoned
+dependabot
+dev
+devenv
 dockershim
 dropdown
 e.g.
@@ -143,31 +168,40 @@ errored
 expr
 fibonacci
 finalizer
+gitops
 govaluate
 gzipped
-Generator
 i.e.
+idempotence
 instantiator
 instantiators
 jenkins
 k3d
 k3s
 k8s-jobs
 kube
+kube-scheduler
+kube-apiserver
+kubectl
 kubelet
 kubernetes
 liveness
 localhost
+maxFailures
+maxSuccess
 memoization
 memoized
 memoizing
+metadata
 minikube
 mutex
 namespace
 namespaces
 natively
+nix.conf
 OpenAPI
 p.m.
+parameterizing
 params
 pprof
 pre-commit
@@ -179,6 +213,8 @@ runtimes
 sandboxed
 stateful
 stderr
+templating
+tolerations
 un-reconciled
 v1
 v1.0
@@ -212,6 +248,7 @@ v3.4
 v3.4.
 v3.5
 validator
+vendored
 versioning
 webHDFS
 webhook
@@ -220,20 +257,3 @@ workflow-controller-configmap
 WorkflowTemplate
 WorkflowTemplates
 yaml
-idempotence
-kube-scheduler
-kube-apiserver
-kubectl
-Makefile
-Devenv
-devenv
-vendored
-nix.conf
-LDFlags
-dev
-dependabot
-CronWorkflow
-CronWorkflows
-maxFailures
-maxSuccess
-gitops
diff --git a/Makefile b/Makefile
@@ -712,7 +712,7 @@ docs-lint: /usr/local/bin/markdownlint
 /usr/local/bin/mkdocs:
 # update this in Nix when upgrading it here
 ifneq ($(USE_NIX), true)
-	python -m pip install mkdocs==1.2.4 mkdocs_material==8.1.9  mkdocs-spellcheck==0.2.1
+	python -m pip install --no-cache-dir -r docs/requirements.txt
 endif
 
 .PHONY: docs
@@ -758,4 +758,3 @@ release-notes: /dev/null
 .PHONY: checksums
 checksums:
 	sha256sum ./dist/argo-*.gz | awk -F './dist/' '{print $$1 $$2}' > ./dist/argo-workflows-cli-checksums.txt
-
diff --git a/README.md b/README.md
@@ -21,11 +21,11 @@ Argo is a [Cloud Native Computing Foundation (CNCF)](https://cncf.io/) graduated
 
 ## Use Cases
 
-* [Machine Learning pipelines](https://argoproj.github.io/argo-workflows/use-cases/machine-learning/)
-* [Data and batch processing](https://argoproj.github.io/argo-workflows/use-cases/data-processing/)
-* [Infrastructure automation](https://argoproj.github.io/argo-workflows/use-cases/infrastructure-automation/)
-* [CI/CD](https://argoproj.github.io/argo-workflows/use-cases/ci-cd/)
-* [Other use cases](https://argoproj.github.io/argo-workflows/use-cases/other/)
+* [Machine Learning pipelines](https://argo-workflows.readthedocs.io/en/stable/use-cases/machine-learning/)
+* [Data and batch processing](https://argo-workflows.readthedocs.io/en/stable/use-cases/data-processing/)
+* [Infrastructure automation](https://argo-workflows.readthedocs.io/en/stable/use-cases/infrastructure-automation/)
+* [CI/CD](https://argo-workflows.readthedocs.io/en/stable/use-cases/ci-cd/)
+* [Other use cases](https://argo-workflows.readthedocs.io/en/stable/use-cases/other/)
 
 ## Why Argo Workflows?
 
@@ -74,12 +74,12 @@ Check out our [Java, Golang and Python clients](docs/client-libraries.md).
 
 ## Quickstart
 
-* [Get started here](docs/quick-start.md)
-* [Walk-through examples](https://argoproj.github.io/argo-workflows/walk-through/)
+* [Get started here](https://argo-workflows.readthedocs.io/en/stable/quick-start/)
+* [Walk-through examples](https://argo-workflows.readthedocs.io/en/stable/walk-through/)
 
 ## Documentation
 
-[View the docs](https://argoproj.github.io/argo-workflows/)
+[View the docs](https://argo-workflows.readthedocs.io/en/stable/)
 
 ## Features
 

diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json
diff --git a/cmd/argo/commands/common/get_test.go b/cmd/argo/commands/common/get_test.go
@@ -422,7 +422,7 @@ func Test_printWorkflowHelperNudges(t *testing.T) {
 
 	securityNudges := "This workflow does not have security context set. " +
 		"You can run your workflow pods more securely by setting it.\n" +
-		"Learn more at https://argoproj.github.io/argo-workflows/workflow-pod-security-context/\n"
+		"Learn more at https://argo-workflows.readthedocs.io/en/stable/workflow-pod-security-context/\n"
 
 	t.Run("SecuredWorkflow", func(t *testing.T) {
 		output := PrintWorkflowHelper(&securedWf, GetFlags{})

diff --git a/cmd/argo/commands/server.go b/cmd/argo/commands/server.go
@@ -138,7 +138,7 @@ See %s`, help.ArgoServer),
 				}
 
 			} else {
-				log.Warn("You are running in insecure mode. Learn how to enable transport layer security: https://argoproj.github.io/argo-workflows/tls/")
+				log.Warn("You are running in insecure mode. Learn how to enable transport layer security: https://argo-workflows.readthedocs.io/en/stable/tls/")
 			}
 
 			modes := auth.Modes{}
@@ -149,7 +149,7 @@ See %s`, help.ArgoServer),
 				}
 			}
 			if reflect.DeepEqual(modes, auth.Modes{auth.Server: true}) {
-				log.Warn("You are running without client authentication. Learn how to enable client authentication: https://argoproj.github.io/argo-workflows/argo-server-auth-mode/")
+				log.Warn("You are running without client authentication. Learn how to enable client authentication: https://argo-workflows.readthedocs.io/en/stable/argo-server-auth-mode/")
 			}
 
 			opts := apiserver.ArgoServerOpts{

diff --git a/config/config.go b/config/config.go
@@ -97,7 +97,7 @@ type Config struct {
 	InitialDelay metav1.Duration `json:"initialDelay,omitempty"`
 
 	// The command/args for each image, needed when the command is not specified and the emissary executor is used.
-	// https://argoproj.github.io/argo-workflows/workflow-executors/#emissary-emissary
+	// https://argo-workflows.readthedocs.io/en/stable/workflow-executors/#emissary-emissary
 	Images map[string]Image `json:"images,omitempty"`
 
 	// Workflow retention by number of workflows

diff --git a/docs/README.md b/docs/README.md
@@ -19,11 +19,11 @@ Argo is a [Cloud Native Computing Foundation (CNCF)](https://cncf.io/) graduated
 
 ## Use Cases
 
-* [Machine Learning pipelines](https://argoproj.github.io/argo-workflows/use-cases/machine-learning/)
-* [Data and batch processing](https://argoproj.github.io/argo-workflows/use-cases/data-processing/)
-* [Infrastructure automation](https://argoproj.github.io/argo-workflows/use-cases/infrastructure-automation/)
-* [CI/CD](https://argoproj.github.io/argo-workflows/use-cases/ci-cd/)
-* [Other use cases](https://argoproj.github.io/argo-workflows/use-cases/other/)
+* [Machine Learning pipelines](https://argo-workflows.readthedocs.io/en/stable/use-cases/machine-learning/)
+* [Data and batch processing](https://argo-workflows.readthedocs.io/en/stable/use-cases/data-processing/)
+* [Infrastructure automation](https://argo-workflows.readthedocs.io/en/stable/use-cases/infrastructure-automation/)
+* [CI/CD](https://argo-workflows.readthedocs.io/en/stable/use-cases/ci-cd/)
+* [Other use cases](https://argo-workflows.readthedocs.io/en/stable/use-cases/other/)
 
 ## Why Argo Workflows?
 

diff --git a/docs/argo-server-sso-argocd.md b/docs/argo-server-sso-argocd.md
@@ -87,7 +87,7 @@ metadata:
 data:
   # SSO Configuration for the Argo server.
   # You must also start argo server with `--auth-mode sso`.
-  # https://argoproj.github.io/argo-workflows/argo-server-auth-mode/
+  # https://argo-workflows.readthedocs.io/en/stable/argo-server-auth-mode/
   sso: |
     # This is the root URL of the OIDC provider (required).
     issuer: https://argo-cd.mydomain.com/api/dex

diff --git a/docs/cli/argo_server.md b/docs/cli/argo_server.md
@@ -10,7 +10,7 @@ argo server [flags]
 
 ```
 
-See https://argoproj.github.io/argo-workflows/argo-server/
+See https://argo-workflows.readthedocs.io/en/stable/argo-server/
 ```
 
 ### Options

diff --git a/docs/offloading-large-workflows.md b/docs/offloading-large-workflows.md
@@ -23,6 +23,6 @@ size limit. To resolve, either enable node status offload as described
 above or look for ways to reduce the size of your workflow manifest:
 
 - Use `withItems` or `withParams` to consolidate similar templates into a single parametrized template
-- Use [template defaults](https://argoproj.github.io/argo-workflows/template-defaults/) to factor shared template options to the workflow level
-- Use [workflow templates](https://argoproj.github.io/argo-workflows/workflow-templates/) to factor frequently-used templates into separate resources
-- Use [workflows of workflows](https://argoproj.github.io/argo-workflows/workflow-of-workflows/) to factor a large workflow into a workflow of smaller workflows
+- Use [template defaults](template-defaults.md) to factor shared template options to the workflow level
+- Use [workflow templates](workflow-templates.md) to factor frequently-used templates into separate resources
+- Use [workflows of workflows](workflow-of-workflows.md) to factor a large workflow into a workflow of smaller workflows
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+mkdocs-material==8.2.6
diff --git a/docs/running-nix.md b/docs/running-nix.md
@@ -4,7 +4,7 @@ Nix is a package manager / build tool which focuses on reproducible build enviro
 Argo Workflows has some basic support for Nix which is enough to get Argo Workflows up and running with minimal effort.
 Here are the steps to follow:
 
-  1. Modify your hosts file and set up a Kubernetes cluster according to [Running Locally](https://argoproj.github.io/argo-workflows/running-locally/). Don't worry about the other instructions.
+  1. Modify your hosts file and set up a Kubernetes cluster according to [Running Locally](running-locally.md). Don't worry about the other instructions.
   1. Install [Nix](https://nixos.org/download.html).
   1. Run `nix develop --extra-experimental-features nix-command --extra-experimental-features flakes ./dev/nix/ --impure` (you can add the extra features as a default in your `nix.conf` file).
   1. Run `devenv up`.

diff --git a/docs/walk-through/artifacts.md b/docs/walk-through/artifacts.md
@@ -113,7 +113,7 @@ Artifacts are packaged as Tarballs and gzipped by default. You may customize thi
 
 ## Artifact Garbage Collection
 
-As of version 3.4 you can configure your Workflow to automatically delete Artifacts that you don't need (visit [artifact repository capability](https://argoproj.github.io/argo-workflows/configure-artifact-repository/) for the current supported store engine).
+As of version 3.4 you can configure your Workflow to automatically delete Artifacts that you don't need (visit [artifact repository capability](../configure-artifact-repository.md) for the current supported store engine).
 
 Artifacts can be deleted `OnWorkflowCompletion` or `OnWorkflowDeletion`. You can specify your Garbage Collection strategy on both the Workflow level and the Artifact level, so for example, you may have temporary artifacts that can be deleted right away but a final output that should be persisted:
 

diff --git a/docs/workflow-controller-configmap.yaml b/docs/workflow-controller-configmap.yaml
@@ -201,7 +201,7 @@ data:
   kubeletInsecure: "false"
 
   # The command/args for each image, needed when the command is not specified and the emissary executor is used.
-  # https://argoproj.github.io/argo-workflows/workflow-executors/#emissary-emissary
+  # https://argo-workflows.readthedocs.io/en/stable/workflow-executors/#emissary-emissary
   images: |
     argoproj/argosay:v2:
       cmd: [/argosay]
@@ -372,7 +372,7 @@ data:
 
   # SSO Configuration for the Argo server.
   # You must also start argo server with `--auth-mode sso`.
-  # https://argoproj.github.io/argo-workflows/argo-server-auth-mode/
+  # https://argo-workflows.readthedocs.io/en/stable/argo-server-auth-mode/
   sso: |
     # This is the root URL of the OIDC provider (required).
     issuer: https://issuer.root.url/