RHDEVDOCS-6997: Initial vale compability assessment for DITA conversion for About OpenShift Pipelines

_attributes/common-attributes.adoc

@@ -1,3 +1,5 @@
+:_mod-docs-content-type: SNIPPET
+
 // The {product-title} attribute provides the context-sensitive name of the relevant OpenShift distribution, for example, "OpenShift Container Platform" or "OKD". The {product-version} attribute provides the product version relative to the distribution, for example "4.9".
 // {product-title} and {product-version} are parsed when AsciiBinder queries the _distro_map.yml file in relation to the base branch of a pull request.
 // See https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#product-name-and-version for more information on this topic.

modules/op-about-finally_tasks.adoc

@@ -1,48 +1,52 @@
 // This module is included in the following assemblies:
 // * about/understanding-openshift-pipelines.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="about-finally_tasks_{context}"]
 = Finally tasks
 
-The `finally` tasks are the final set of tasks specified using the `finally` field in the pipeline YAML file. A `finally` task always executes the tasks within the pipeline, irrespective of whether the pipeline runs are executed successfully. The `finally` tasks are executed in parallel after all the pipeline tasks are run, before the corresponding pipeline exits.
+[role="_abstract"]
+You can use `finally` tasks to execute a final set of tasks in your pipeline regardless of whether the previous tasks succeed or fail. These tasks run in parallel after all other pipeline tasks finish, allowing you to perform cleanup or notification actions before the pipeline exits.
 
-You can configure a `finally` task to consume the results of any task within the same pipeline. This approach does not change the order in which this final task is run. It is executed in parallel with other final tasks after all the non-final tasks are executed.
+The `finally` tasks are the final set of tasks specified using the `finally` field in the pipeline YAML file. A `finally` task always runs the tasks within the pipeline, irrespective of whether the pipeline runs succeed.
 
-The following example shows a code snippet of the `clone-cleanup-workspace` pipeline. This code clones the repository into a shared workspace and cleans up the workspace. After executing the pipeline tasks, the `cleanup` task specified in the `finally` section of the pipeline YAML file cleans up the workspace.
+You can configure a `finally` task to consume the results of any task within the same pipeline. This approach does not change the order in which this final task runs.
+
+The following example shows a code snippet of the `clone-cleanup-workspace` pipeline. This code clones the repository into a shared workspace and cleans up the workspace. After the pipeline tasks finish, the `cleanup` task specified in the `finally` section of the pipeline YAML file cleans up the workspace.
 
 [source,yaml]
 ----
 apiVersion: tekton.dev/v1
 kind: Pipeline
 metadata:
-  name: clone-cleanup-workspace <1>
+  name: clone-cleanup-workspace
 spec:
   workspaces:
-    - name: git-source <2>
+    - name: git-source
   tasks:
-    - name: clone-app-repo <3>
+    - name: clone-app-repo
       taskRef:
         name: git-clone-from-catalog
       params:
         - name: url
-          value: https://github.com/tektoncd/community.git
+          value: git.example.com/tektoncd/community.git
         - name: subdirectory
           value: application
       workspaces:
         - name: output
           workspace: git-source
   finally:
-    - name: cleanup <4>
-      taskRef: <5>
+    - name: cleanup
+      taskRef:
         name: cleanup-workspace
-      workspaces: <6>
+      workspaces:
         - name: source
           workspace: git-source
     - name: check-git-commit
-      params: <7>
+      params:
         - name: commit
           value: $(tasks.clone-app-repo.results.commit)
-      taskSpec: <8>
+      taskSpec:
         params:
           - name: commit
         steps:
@@ -53,11 +57,19 @@ spec:
                 exit 1
               fi
 ----
-<1> Unique name of the pipeline.
-<2> The shared workspace where the git repository is cloned.
-<3> The task to clone the application repository to the shared workspace.
-<4> The task to clean-up the shared workspace.
-<5> A reference to the task that is to be executed in the task run.
-<6> A shared storage volume that a task in a pipeline needs at runtime to receive input or provide output.
-<7> A list of parameters required for a task. If a parameter does not have an implicit default value, you must explicitly set its value.
-<8> Embedded task definition.
+
+`metadata.name`:: Unique name of the pipeline.
+
+`spec.workspaces[0].name`:: The shared workspace where the git repository is copied.
+
+`spec.tasks[0].name`:: The task to clone the application repository to the shared workspace.
+
+`spec.finally[0].name`:: The task to clean-up the shared workspace.
+
+`spec.finally.taskRef`:: A reference to the task that runs in the task run.
+
+`spec.finally[0].name.workspaces`:: A shared storage volume that a task in a pipeline needs at runtime to receive input or offer output.
+
+`spec.finally[1].name.params`:: A list of parameters required for a task. If a parameter does not have an implicit default value, you must explicitly set its value.
+
+`spec.finally[1].name.taskSpec`:: Embedded task definition.

modules/op-about-pipelinerun.adoc

@@ -1,33 +1,37 @@
 // This module is included in the following assemblies:
 // * about/understanding-openshift-pipelines.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="about-pipelinerun_{context}"]
-= PipelineRun
+= Pipeline run
+
+[role="_abstract"]
+You can use a `PipelineRun` resource to instantiate and execute a pipeline with specific inputs, outputs, and credentials. This resource binds a pipeline to a workspace and parameter values, enabling you to run your CI/CD workflow for a specific scenario.
 
 A `PipelineRun` is a type of resource that binds a pipeline, workspaces, credentials, and a set of parameter values specific to a scenario to run the CI/CD workflow.
 
-A pipeline run is the running instance of a pipeline. It instantiates a pipeline for execution with specific inputs, outputs, and execution parameters on a cluster. It also creates a task run for each task in the pipeline run.
+A pipeline run is the running instance of a pipeline. It also creates a task run for each task in the pipeline run.
 
 The pipeline runs the tasks sequentially until they are complete or a task fails. The `status` field tracks and the progress of each task run and stores it for monitoring and auditing purposes.
 
 The following example runs the `build-and-deploy` pipeline with relevant resources and parameters:
 [source,yaml]
 ----
-apiVersion: tekton.dev/v1 <1>
-kind: PipelineRun <2>
+apiVersion: tekton.dev/v1
+kind: PipelineRun
 metadata:
-  name: build-deploy-api-pipelinerun <3>
+  name: build-deploy-api-pipelinerun
 spec:
   pipelineRef:
-    name: build-and-deploy <4>
-  params: <5>
+    name: build-and-deploy
+  params:
   - name: deployment-name
     value: vote-api
   - name: git-url
     value: https://github.com/openshift-pipelines/vote-api.git
   - name: IMAGE
     value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-api
-  workspaces: <6>
+  workspaces:
   - name: shared-workspace
     volumeClaimTemplate:
       spec:
@@ -37,9 +41,15 @@ spec:
           requests:
             storage: 500Mi
 ----
-<1> Pipeline run API version `v1`.
-<2> The type of Kubernetes object. In this example, `PipelineRun`.
-<3> Unique name to identify this pipeline run.
-<4> Name of the pipeline to be run. In this example, `build-and-deploy`.
-<5> The list of parameters required to run the pipeline.
-<6> Workspace used by the pipeline run.
+
+`apiVersion`:: Pipeline run API version `v1`.
+
+`kind`:: The type of Kubernetes object. In this example, `PipelineRun`.
+
+`metadata.name`:: Unique name to identify this pipeline run.
+
+`spec.pipelineRef.name`:: Name of the pipeline to run. In this example, `build-and-deploy`.
+
+`spec.params`:: The list of parameters required to run the pipeline.
+
+`spec.workspaces`:: Workspace used by the pipeline run.

modules/op-about-pipelines.adoc

@@ -1,25 +1,29 @@
 // This module is included in the following assemblies:
 // * about/understanding-openshift-pipelines.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="about-pipelines_{context}"]
 = Pipelines
 
-A `Pipeline` is a collection of `Task` resources arranged in a specific order of execution. They are executed to construct complex workflows that automate the build, deployment and delivery of applications. You can define a CI/CD workflow for your application using pipelines containing one or more tasks.
+[role="_abstract"]
+You can use a `Pipeline` resource to arrange a collection of tasks in a specific order of execution. By defining a pipeline, you construct complex workflows that automate the build, deployment, and delivery of your applications.
 
-A `Pipeline` resource definition consists of a number of fields or attributes, which together enable the pipeline to accomplish a specific goal. Each `Pipeline` resource definition must contain at least one `Task` resource, which ingests specific inputs and produces specific outputs. The pipeline definition can also optionally include _Conditions_, _Workspaces_, _Parameters_, or _Resources_ depending on the application requirements.
+A `Pipeline` is a collection of `Task` resources arranged in a specific order of execution. You run them to construct complex workflows that automate the build, deployment and delivery of applications by using one or more tasks to define a CI/CD workflow for your application.
 
-The following example shows the `build-and-deploy` pipeline, which builds an application image from a Git repository using the `buildah` task provided in the `openshift-pipelines` namespace:
+A `Pipeline` resource definition consists of several fields or attributes, which together enable the pipeline to run a specific goal. Each `Pipeline` resource definition must contain at least one `Task` resource, which obtains specific inputs and produces specific outputs. The pipeline definition can also optionally include several _Conditions_, _Workspaces_, _Parameters_, or _Resources_ depending on the application requirements.
+
+The following example shows the `build-and-deploy` pipeline, which builds an application image from a Git repository by using the `buildah` task provided in the `openshift-pipelines` namespace:
 
 [source,yaml,subs="attributes+"]
 ----
-apiVersion: tekton.dev/v1 <1>
-kind: Pipeline <2>
+apiVersion: tekton.dev/v1
+kind: Pipeline
 metadata:
-  name: build-and-deploy <3>
-spec: <4>
-  workspaces: <5>
+  name: build-and-deploy
+spec:
+  workspaces:
   - name: shared-workspace
-  params: <6>
+  params:
   - name: deployment-name
     type: string
     description: name of the deployment to be patched
@@ -33,7 +37,7 @@ spec: <4>
   - name: IMAGE
     type: string
     description: image to be built from the code
-  tasks: <7>
+  tasks:
   - name: fetch-repository
     taskRef:
       resolver: cluster
@@ -56,7 +60,7 @@ spec: <4>
       value: "true"
     - name: REVISION
       value: $(params.git-revision)
-  - name: build-image <8>
+  - name: build-image
     taskRef:
       resolver: cluster
       params:
@@ -76,13 +80,13 @@ spec: <4>
       value: $(params.IMAGE)
     runAfter:
     - fetch-repository
-  - name: apply-manifests <9>
+  - name: apply-manifests
     taskRef:
       name: apply-manifests
     workspaces:
     - name: source
       workspace: shared-workspace
-    runAfter: <10>
+    runAfter:
     - build-image
   - name: update-deployment
     taskRef:
@@ -98,18 +102,28 @@ spec: <4>
     runAfter:
     - apply-manifests
 ----
-<1> Pipeline API version `v1`.
-<2> Specifies the type of Kubernetes object. In this example, `Pipeline`.
-<3> Unique name of this pipeline.
-<4> Specifies the definition and structure of the pipeline.
-<5> Workspaces used across all the tasks in the pipeline.
-<6> Parameters used across all the tasks in the pipeline.
-<7> Specifies the list of tasks used in the pipeline.
-<8> Task `build-image`, which uses the `buildah` task provided in the `openshift-pipelines` namespace to build application images from a given Git repository.
-<9> Task `apply-manifests`, which uses a user-defined task with the same name.
-<10> Specifies the sequence in which tasks are run in a pipeline. In this example, the `apply-manifests` task is run only after the `build-image` task is completed.
+
+`apiVersion`:: Pipeline API version `v1`.
+
+`kind`:: Specifies the type of Kubernetes object. In this example, `Pipeline`.
+
+`metadata.name`:: Unique name of this pipeline.
+
+`spec`:: Specifies the definition and structure of the pipeline.
+
+`spec.workspaces`:: Workspaces used across all the tasks in the pipeline.
+
+`spec.params`:: Parameters used across all the tasks in the pipeline.
+
+`tasks[0].name`:: Specifies the list of tasks used in the pipeline.
+
+`tasks[1].name`:: Task `build-image`, which uses the `buildah` task provided in the `openshift-pipelines` namespace to build application images from a given Git repository.
+
+`tasks[2].name`:: Task `apply-manifests`, which uses a user-defined task with the same name.
+
+`tasks[2].name.runAfter`:: Specifies the sequence in which tasks run in a pipeline. In this example, the `apply-manifests` task runs only after the `build-image` task finishes.
 
 [NOTE]
 ====
-The {pipelines-title} Operator installs the Buildah task in the `openshift-pipelines` namespace and creates the `pipeline` service account with sufficient permission to build and push an image. The Buildah task can fail when associated with a different service account with insufficient permissions.
-====
+The {pipelines-title} Operator installs the Buildah task in the `openshift-pipelines` namespace and creates the `pipeline` service account with enough permissions to build and push an image. The Buildah task can fail when associated with a different service account with insufficient permissions.
+====

modules/op-about-podtemplate.adoc

@@ -1,12 +1,16 @@
 // This module is included in the following assemblies:
 // * about/understanding-openshift-pipelines.adoc
 
+:_mod-docs-content-type: CONCEPT
 [id="about-podtemplate_{context}"]
 = Pod templates
 
-Optionally, you can define a _pod template_ in a `PipelineRun` or `TaskRun` custom resource (CR). You can use any parameters available for a `Pod` CR in the pod template. When creating pods for executing the pipeline or task, {pipelines-shortname} sets these parameters for every pod.
+[role="_abstract"]
+You can define a pod template in a `PipelineRun` or `TaskRun` custom resource (CR) to configure the pods that execute your tasks. This allows you to set specific parameters, such as security contexts or user IDs, for every pod created during the pipeline or task run.
 
-For example, you can use a pod template to make the pod execute as a user and not as root.
+Optionally, you can define a _pod template_ in a `PipelineRun` or `TaskRun` custom resource (CR). You can use any parameters available for a `Pod` CR in the pod template. When creating pods for running the pipeline or task, {pipelines-shortname} sets these parameters for every pod.
+
+For example, you can use a pod template to make the pod run as a user and not as root.
 
 For a pipeline run, you can define a pod template in the `pipelineRunTemplate.podTemplate` spec, as in the following example:
 
@@ -29,7 +33,7 @@ spec:
 
 [NOTE]
 ====
-In the earlier API version `v1beta1`, the pod template for a `PipelineRun` CR was specified as `podTemplate` directly in the `spec:` section. This format is not supported in the `v1` API.
+In the earlier API version `v1beta1`, the pod template for a `PipelineRun` CR defined `podTemplate` directly in the `spec:` section. This format is not supported in the `v1` API.
 ====
 
 For a task run, you can define a pod template in the `podTemplate` spec, as in the following example:
@@ -50,4 +54,4 @@ spec:
     securityContext:
       runAsNonRoot: true
       runAsUser: 1001
-----
+----

modules/op-about-stepactions.adoc

@@ -5,9 +5,12 @@
 [id="about-stepactions_{context}"]
 = Step actions
 
+[role="_abstract"]
+You can use a `StepAction` custom resource (CR) to define a reusable action that a step performs. By referencing a `StepAction` object from a step, you can share and reuse action definitions across multiple tasks or reference actions from external sources.
+
 A step is a part of a task. If you define a step in a task, you cannot reference this step from another task.
 
-However, you can optionally define a _step action_ in a `StepAction` custom resource (CR). This CR contains the action that a step performs. You can reference a `StepAction` object from a step to create a step that performs the action. You can also use resolvers to reference a `StepAction` definition that is available from an external source.
+This CR contains the action that a step performs. You can reference a `StepAction` object from a step to create a step that performs the action. You can also use resolvers to reference a `StepAction` definition that is available from an external source.
 
 The following examples shows a `StepAction` CR named `apply-manifests-action`. This step action applies manifests from a source tree to your {OCP} environment:
 
@@ -21,7 +24,7 @@ spec:
   params:
   - name: working_dir
     description: The working directory where the source is located
-    type: string # <1>
+    type: string
     default: "/workspace/source"
   - name: manifest_dir
     description: The directory in source that contains yaml manifests
@@ -38,7 +41,8 @@ spec:
       #!/usr/bin/env bash
       oc apply -f "$MANIFEST_DIR" | tee $(results.output)
 ----
-<1> The `type` specification for a parameter is optional.
+
+`spec.params[n].name.type`:: The `type` specification for a parameter is optional.
 
 The `StepAction` CR does not include definitions of workspaces. Instead, the step action expects that the task that includes the action also provides the mounted source tree, typically using a workspace.