chore: backport documentation changes to v3.5.2

relates to argoproj#12414 - [x] move over files to help with readthedocs build - [x] .readthedocs.yaml - [x] Makefile - [x] mkdocs.yml - [x] hack/check-mkdocs.sh - [x] docs/requirements.txt - [x] change links from github pages to readthedocs v3.5.2 Signed-off-by: jmeridth <[email protected]>
jmeridth · Jan 3, 2024 · 7d77a72 · 7d77a72
1 parent 5b6ad2b
commit 7d77a72
Show file tree

Hide file tree

Showing 465 changed files with 516 additions and 501 deletions.
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/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
@@ -20,11 +20,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/v3.5.2/use-cases/machine-learning/)
+* [Data and batch processing](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/data-processing/)
+* [Infrastructure automation](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/infrastructure-automation/)
+* [CI/CD](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/ci-cd/)
+* [Other use cases](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/other/)
 
 ## Why Argo Workflows?
 
@@ -71,11 +71,11 @@ 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/)
+* [Walk-through examples](https://argo-workflows.readthedocs.io/en/v3.5.2/walk-through/)
 
 ## Documentation
 
-[View the docs](https://argoproj.github.io/argo-workflows/)
+[View the docs](https://argo-workflows.readthedocs.io/en/v3.5.2/)
 
 ## 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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/use-cases/machine-learning/)
+* [Data and batch processing](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/data-processing/)
+* [Infrastructure automation](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/infrastructure-automation/)
+* [CI/CD](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/ci-cd/)
+* [Other use cases](https://argo-workflows.readthedocs.io/en/v3.5.2/use-cases/other/)
 
 ## Why Argo Workflows?
 
@@ -69,11 +69,11 @@ Check out our [Java, Golang and Python clients](https://github.com/argoproj/argo
 ## Quickstart
 
 * [Get started here](https://github.com/argoproj/argo-workflows/blob/master/docs/quick-start.md)
-* [Walk-through examples](https://argoproj.github.io/argo-workflows/walk-through/)
+* [Walk-through examples](https://argo-workflows.readthedocs.io/en/v3.5.2/walk-through/)
 
 ## Documentation
 
-[View the docs](https://argoproj.github.io/argo-workflows/)
+[View the docs](https://argo-workflows.readthedocs.io/en/v3.5.2/)
 
 ## Features
 

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/v3.5.2/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/v3.5.2/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](https://argo-workflows.readthedocs.io/en/v3.5.2/template-defaults/) to factor shared template options to the workflow level
+- Use [workflow templates](https://argo-workflows.readthedocs.io/en/v3.5.2/workflow-templates/) to factor frequently-used templates into separate resources
+- Use [workflows of workflows](https://argo-workflows.readthedocs.io/en/v3.5.2/workflow-of-workflows/) 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/retries.md b/docs/retries.md
@@ -31,7 +31,7 @@ Use `retryPolicy` to choose which failure types to retry:
 - `Always`: Retry all failed steps
 - `OnFailure`: Retry steps whose main container is marked as failed in Kubernetes
 - `OnError`: Retry steps that encounter Argo controller errors, or whose init or wait containers fail
-- `OnTransientError`: Retry steps that encounter errors [defined as transient](https://github.com/argoproj/argo-workflows/blob/master/util/errors/errors.go), or errors matching the `TRANSIENT_ERROR_PATTERN` [environment variable](https://argoproj.github.io/argo-workflows/environment-variables/). Available in version 3.0 and later.
+- `OnTransientError`: Retry steps that encounter errors [defined as transient](https://github.com/argoproj/argo-workflows/blob/master/util/errors/errors.go), or errors matching the `TRANSIENT_ERROR_PATTERN` [environment variable](https://argo-workflows.readthedocs.io/en/v3.5.2/environment-variables/). Available in version 3.0 and later.
 
 The `retryPolicy` applies even if you also specify an `expression`, but in version 3.5 or later the default policy means the expression makes the decision unless you explicitly specify a policy.
 

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](https://argo-workflows.readthedocs.io/en/v3.5.2/running-locally/). 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](https://argo-workflows.readthedocs.io/en/v3.5.2/configure-artifact-repository/) 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/v3.5.2/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/v3.5.2/argo-server-auth-mode/
   sso: |
     # This is the root URL of the OIDC provider (required).
     issuer: https://issuer.root.url/

diff --git a/examples/README.md b/examples/README.md
@@ -1,3 +1,3 @@
 # Documentation by Example
 
-This has been moved to [the docs](https://argoproj.github.io/argo-workflows/walk-through/).
+This has been moved to [the docs](https://argo-workflows.readthedocs.io/en/v3.5.2/walk-through/).
diff --git a/examples/input-artifact-s3.yaml b/examples/input-artifact-s3.yaml
@@ -27,7 +27,7 @@ spec:
           key: path/in/bucket
           # Specify the bucket region. Note that if you want Argo to figure out this automatically,
           # you can set additional statement policy that allows `s3:GetBucketLocation` action.
-          # For details, check out: https://argoproj.github.io/argo-workflows/configure-artifact-repository/#configuring-aws-s3
+          # For details, check out: https://argo-workflows.readthedocs.io/en/v3.5.2/configure-artifact-repository/#configuring-aws-s3
           region: us-west-2
           # accessKeySecret and secretKeySecret are secret selectors.
           # It references the k8s secret named 'my-s3-credentials'.

diff --git a/examples/intermediate-parameters.yaml b/examples/intermediate-parameters.yaml
@@ -1,5 +1,5 @@
 # This example demonstrates the ability to use intermediate parameter.
-# See https://argoproj.github.io/argo-workflows/intermediate-inputs/ for details.
+# See https://argo-workflows.readthedocs.io/en/v3.5.2/intermediate-inputs/ for details.
 apiVersion: argoproj.io/v1alpha1
 kind: Workflow
 metadata:

diff --git a/examples/key-only-artifact.yaml b/examples/key-only-artifact.yaml
@@ -1,5 +1,5 @@
 # this example shows how to use key-only artifacts - introduced in v3.0
-# https://argoproj.github.io/argo-workflows/key-only-artifacts/
+# https://argo-workflows.readthedocs.io/en/v3.5.2/key-only-artifacts/
 apiVersion: argoproj.io/v1alpha1
 kind: Workflow
 metadata:

diff --git a/examples/output-artifact-s3.yaml b/examples/output-artifact-s3.yaml
@@ -32,7 +32,7 @@ spec:
           bucket: my-bucket
           # Specify the bucket region. Note that if you want Argo to figure out this automatically,
           # you can set additional statement policy that allows `s3:GetBucketLocation` action.
-          # For details, check out: https://argoproj.github.io/argo-workflows/configure-artifact-repository/#configuring-aws-s3
+          # For details, check out: https://argo-workflows.readthedocs.io/en/v3.5.2/configure-artifact-repository/#configuring-aws-s3
           region: us-west-2
 
           # NOTE: by default, output artifacts are automatically tarred and gzipped before saving.

diff --git a/hack/check-mkdocs.sh b/hack/check-mkdocs.sh
@@ -3,11 +3,7 @@ set -eu
 
 echo "Checking all docs are listed in mkdocs.yml..."ß
 
-find docs -name '*.md' | grep -v "^docs/proposals" | sed 's|^docs/||' | while read -r f ; do
-  if ! grep -Fq "$f" mkdocs.yml; then
-      echo "❌ $f is missing from mkdocs.yml" >&2
-      exit 1
-  fi
-done
+# https://www.mkdocs.org/user-guide/configuration/#validation since 1.5.0
+mkdocs build --strict
 
 echo "✅ Success - all docs appear to be listed in mkdocs.yml"
diff --git a/hack/release-notes.md b/hack/release-notes.md
@@ -6,7 +6,7 @@ Find out on [our blog](https://blog.argoproj.io) and [changelog](https://github.
 
 ## Breaking Changes and Known Issues
 
-Check the [upgrading guide](https://argoproj.github.io/argo-workflows/upgrading/) and search for [existing issues on GitHub](https://github.com/argoproj/argo-workflows/issues).
+Check the [upgrading guide](https://argo-workflows.readthedocs.io/en/v3.5.2/upgrading/) and search for [existing issues on GitHub](https://github.com/argoproj/argo-workflows/issues).
 
 ## Installation
 

diff --git a/manifests/README.md b/manifests/README.md
@@ -1,3 +1,3 @@
 # Argo Install Manifests
 
-Please read [installation](https://argoproj.github.io/argo-workflows/installation/)
+Please read [installation](https://argo-workflows.readthedocs.io/en/v3.5.2/installation/)
diff --git a/manifests/quick-start/base/agent-role.yaml b/manifests/quick-start/base/agent-role.yaml
@@ -1,4 +1,4 @@
-# https://argoproj.github.io/argo-workflows/workflow-rbac/
+# https://argo-workflows.readthedocs.io/en/v3.5.2/workflow-rbac/
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:

diff --git a/manifests/quick-start/base/artifactgc-role.yaml b/manifests/quick-start/base/artifactgc-role.yaml
@@ -1,4 +1,4 @@
-# https://argoproj.github.io/argo-workflows/workflow-rbac/
+# https://argo-workflows.readthedocs.io/en/v3.5.2/workflow-rbac/
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,5 +1,6 @@
 site_name: Argo Workflows - The workflow engine for Kubernetes
 repo_url: https://github.com/argoproj/argo-workflows
+edit_uri: https://github.com/argoproj/argo-workflows/edit/main/docs
 strict: true
 theme:
   name: material
@@ -33,6 +34,13 @@ markdown_extensions:
   - pymdownx.details
   - toc:
       permalink: true
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+exclude_docs: |
+  proposals/
+
 nav:
   - Home: README.md
   - Getting Started:

diff --git a/pkg/apiclient/_.primary.swagger.json b/pkg/apiclient/_.primary.swagger.json
@@ -13,7 +13,7 @@
   "host": "localhost:2746",
   "info": {
     "title": "Argo Workflows API",
-    "description": "Argo Workflows is an open source container-native workflow engine for orchestrating parallel jobs on Kubernetes. For more information, please see https://argoproj.github.io/argo-workflows/",
+    "description": "Argo Workflows is an open source container-native workflow engine for orchestrating parallel jobs on Kubernetes. For more information, please see https://argo-workflows.readthedocs.io/en/v3.5.2/",
     "version": "VERSION"
   },
   "securityDefinitions": {

diff --git a/pkg/apis/workflow/v1alpha1/workflow_types.go b/pkg/apis/workflow/v1alpha1/workflow_types.go
@@ -1169,7 +1169,7 @@ func (a *ArtifactLocation) Get() (ArtifactLocationType, error) {
 	} else if a.S3 != nil {
 		return a.S3, nil
 	}
-	return nil, fmt.Errorf("You need to configure artifact storage. More information on how to do this can be found in the docs: https://argoproj.github.io/argo-workflows/configure-artifact-repository/")
+	return nil, fmt.Errorf("You need to configure artifact storage. More information on how to do this can be found in the docs: https://argo-workflows.readthedocs.io/en/v3.5.2/configure-artifact-repository/")
 }
 
 // SetType sets the type of the artifact to type the argument.

diff --git a/pkg/apis/workflow/v1alpha1/workflow_types_test.go b/pkg/apis/workflow/v1alpha1/workflow_types_test.go
@@ -433,7 +433,7 @@ func TestArtifactLocation_Get(t *testing.T) {
 
 	v, err = (&ArtifactLocation{}).Get()
 	assert.Nil(t, v)
-	assert.EqualError(t, err, "You need to configure artifact storage. More information on how to do this can be found in the docs: https://argoproj.github.io/argo-workflows/configure-artifact-repository/")
+	assert.EqualError(t, err, "You need to configure artifact storage. More information on how to do this can be found in the docs: https://argo-workflows.readthedocs.io/en/v3.5.2/configure-artifact-repository/")
 
 	v, _ = (&ArtifactLocation{Azure: &AzureArtifact{}}).Get()
 	assert.IsType(t, &AzureArtifact{}, v)

diff --git a/sdks/python/client/argo_workflows/__init__.py b/sdks/python/client/argo_workflows/__init__.py
diff --git a/sdks/python/client/argo_workflows/api/archived_workflow_service_api.py b/sdks/python/client/argo_workflows/api/archived_workflow_service_api.py
diff --git a/sdks/python/client/argo_workflows/api/artifact_service_api.py b/sdks/python/client/argo_workflows/api/artifact_service_api.py