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 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 28, 2023 · 4791ff6 · 4791ff6
1 parent dbf4215
commit 4791ff6
Show file tree

Hide file tree

Showing 467 changed files with 519 additions and 510 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
@@ -18,8 +18,6 @@ permissions:
 jobs:
   docs:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write # for publishing the docs to GH Pages
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -44,10 +42,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/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/

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/stable/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/stable/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/stable/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/stable/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/stable/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/stable/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/stable/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/stable/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/stable/workflow-rbac/
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,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/stable/",
     "version": "VERSION"
   },
   "securityDefinitions": {

diff --git a/pkg/apis/workflow/v1alpha1/workflow_types.go b/pkg/apis/workflow/v1alpha1/workflow_types.go
@@ -1173,7 +1173,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/stable/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
@@ -435,7 +435,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/stable/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
diff --git a/sdks/python/client/argo_workflows/api/cluster_workflow_template_service_api.py b/sdks/python/client/argo_workflows/api/cluster_workflow_template_service_api.py
diff --git a/sdks/python/client/argo_workflows/api/cron_workflow_service_api.py b/sdks/python/client/argo_workflows/api/cron_workflow_service_api.py