Merge pull request #87 from smccarthy-ie/fix-root-level-extn-doc

docs: fix root-level extn docs, clean up formatting

doc/generate-kuadrant-rate-limit-policy.md

@@ -1,20 +1,20 @@
 ## Generate Kuadrant RateLimitPolicy object from OpenAPI 3
 
-The `kuadrantctl generate kuadrant ratelimitpolicy` command generates an [Kuadrant RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/)
-from your [OpenAPI Specification (OAS) 3.x](https://spec.openapis.org/oas/latest.html) powered with [kuadrant extensions](openapi-kuadrant-extensions.md).
+The `kuadrantctl generate kuadrant ratelimitpolicy` command generates a [Kuadrant RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/)
+from your [OpenAPI Specification (OAS) 3.x document](https://spec.openapis.org/oas/latest.html) powered with [Kuadrant extensions](openapi-kuadrant-extensions.md).
 
 ### OpenAPI specification
 
-An OpenAPI document resource can be provided to the cli by one of the following channels:
+An OpenAPI document resource can be provided to the Kuadrant CLI in one of the following ways:
 
 * Filename in the available path.
 * URL format (supported schemes are HTTP and HTTPS). The CLI will try to download from the given address.
-* Read from stdin standard input stream.
+* Read from `stdin` standard input stream.
 
 ### Usage
 
 ```shell
-Generate Kuadrant RateLimitPolicy from OpenAPI 3.0.X
+Generate Kuadrant RateLimitPolicy from OpenAPI 3.0.x
 
 Usage:
   kuadrantctl generate kuadrant ratelimitpolicy [flags]
@@ -28,31 +28,31 @@ Global Flags:
   -v, --verbose   verbose output
 ```
 
-> Under the example folder there are examples of OAS 3 that can be used to generate the resources
+> **Note**: The `kuadrantctl/examples` directory in GitHub includes sample OAS 3 files that you can use to generate the resources.
 
-### User Guide
+### Procedure
 
-* Clone the repo 
+1. Clone the Git repository as follows: 
 ```bash
 git clone https://github.com/Kuadrant/kuadrantctl.git
 cd kuadrantctl
-```
-* Setup a cluster, Istio and Gateway API CRDs and Kuadrant
+ ```
+2. Set up a cluster, Istio and Gateway API CRDs, and Kuadrant as follows: 
 
-Use our single-cluster quick start script - this will install Kuadrant in a local `kind` cluster: https://docs.kuadrant.io/getting-started-single-cluster/
+* Use the single-cluster quick start script to install Kuadrant in a local `kind` cluster: https://docs.kuadrant.io/getting-started-single-cluster/.
 
-* Build and install CLI in `bin/kuadrantctl` path
+3. Build and install the CLI in `bin/kuadrantctl` path as follows:
 ```bash
 make install
 ```
 
-* Deploy petstore backend API
+4. Deploy the Petstore backend API as follows:
 ```bash
 kubectl create namespace petstore
 kubectl apply -n petstore -f examples/petstore/petstore.yaml
 ```
-* Let's create Petstore's OpenAPI spec
 
+5. Create the Petstore OpenAPI definition as follows:
 <details>
 
 ```yaml
@@ -62,7 +62,7 @@ openapi: "3.0.3"
 info:
   title: "Pet Store API"
   version: "1.0.0"
-x-kuadrant:
+x-kuadrant:  ## Root-level Kuadrant extension
   route:
     name: "petstore"
     namespace: "petstore"
@@ -75,7 +75,7 @@ servers:
   - url: https://example.io/v1
 paths:
   /cat:
-    x-kuadrant:  ## Path level Kuadrant Extension
+    x-kuadrant:  ## Path-level Kuadrant extension
       backendRefs:
         - name: petstore
           port: 80
@@ -101,7 +101,7 @@ paths:
           description: "invalid input"
   /dog:
     get:  # Added to the route and rate limited
-      x-kuadrant:  ## Operation level Kuadrant Extension
+      x-kuadrant:  ## Operation-level Kuadrant extension
         backendRefs:
           - name: petstore
             port: 80
@@ -118,7 +118,7 @@ paths:
         405:
           description: "invalid input"
     post:  # Added to the route and NOT rate limited
-      x-kuadrant:  ## Operation level Kuadrant Extension
+      x-kuadrant:  ## Operation-level Kuadrant extension
         backendRefs:
           - name: petstore
             port: 80
@@ -129,46 +129,44 @@ paths:
           description: "invalid input"
 EOF
 ```
-
 </details>
 
-> **NOTE**: `servers` base path not included. WIP in following up PRs.
+> **Note**: The `servers` base path is not included. This is work-in-progress in follow-up PRs.
 
-| Operation | Applied config |
+| Operation | Applied configuration |
 | --- | --- |
-| `GET /cat` | It should return 200 Ok and be rate limited (1 req / 10 seconds)  |
-| `POST /cat`  | Not added to the HTTPRoute. It should return 404 Not Found  |
-| `GET /dog`  | It should return 200 Ok and be rate limited (3 req / 10 seconds) |
-| `POST /dog`   | It should return 200 Ok and NOT rate limited  |
+| `GET /cat` | Should return 200 OK and be rate limited (1 req / 10 seconds). |
+| `POST /cat`  | Not added to the HTTPRoute. Should return 404 Not Found. |
+| `GET /dog`  | Should return 200 OK and be rate limited (3 req / 10 seconds). |
+| `POST /dog`   | Should return 200 OK and NOT rate limited. |
 
 
-* Create the HTTPRoute using the CLI
+6. Create the HTTPRoute by using the CLI as follows:
 ```bash
 bin/kuadrantctl generate gatewayapi httproute --oas petstore-openapi.yaml | kubectl apply -n petstore -f -
 ```
 
-* Create the Rate Limit Policy
+7. Create the rate limit policy as follows:
 ```bash
 bin/kuadrantctl generate kuadrant ratelimitpolicy --oas petstore-openapi.yaml | kubectl apply -n petstore -f -
 ```
 
-* Test OpenAPI endpoints
-  * `GET /cat` -> It should return 200 Ok and be rate limited (1 req / 10 seconds)
+8. Test the OpenAPI endpoints as follows:
 
+  * `GET /cat` - Should return 200 OK and be rate limited (1 req / 10 seconds).
 ```bash
 curl --resolve example.com:9080:127.0.0.1 -v "http://example.com:9080/cat"
 ```
-  *   `POST /cat` -> Not added to the HTTPRoute. It should return 404 Not Found
+  *   `POST /cat` - Not added to the HTTPRoute. Should return 404 Not Found.
 ```bash
 curl --resolve example.com:9080:127.0.0.1 -v -X POST "http://example.com:9080/cat"
 ```
-  * `GET /dog` -> It should return 200 Ok and be rate limited (3 req / 10 seconds)
+  * `GET /dog` - Should return 200 OK and be rate limited (3 req / 10 seconds).
 
 ```bash
 curl --resolve example.com:9080:127.0.0.1 -v "http://example.com:9080/dog"
 ```
-
-   *  `POST /dog` -> It should return 200 Ok and NOT rate limited
+  *  `POST /dog` - Should return 200 OK and NOT rate limited.
 
 ```bash
 curl --resolve example.com:9080:127.0.0.1 -v -X POST "http://example.com:9080/dog"

doc/kuadrantctl-ci-cd.md

@@ -1,25 +1,27 @@
 # kuadrantctl - CI/CD with Tekton and Argo CD
 
-This guide demonstrates setting up a CI/CD pipeline using Tekton to deploy Kubernetes Gateway API and Kuadrant resources generated by `kuadrantctl`, from an OpenAPI specification. In this example, these resources are applied directly to the cluster where Tekton is running.
+This guide demonstrates setting up a CI/CD pipeline by using Tekton to deploy Kubernetes Gateway API and Kuadrant resources generated by `kuadrantctl`, from an OpenAPI definition. In this example, these resources are applied directly to the cluster where Tekton is running.
 
 ## Prerequisites
 
-- Kuadrant, and all of its pre-requisites, is installed onto a cluster
-- [Tekton Pipelines](https://tekton.dev/) installed on your Kubernetes or OpenShift cluster.
-- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) configured to communicate with your cluster (i.e you have a kubectl config available with access to your cluster)
-- [Tekton CLI `tkn`](https://tekton.dev/docs/cli/) (optional) for easier interaction with Tekton resources.
+- Kuadrant, and all of its prerequisites, installed on a Kubernetes or OpenShift cluster.
+- [Tekton Pipelines](https://tekton.dev/) installed on your cluster.
+- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) configured with access to communicate with your cluster.
+- Optional: [Tekton CLI `tkn`](https://tekton.dev/docs/cli/) for easier interaction with Tekton resources.
 
-## Setup
+## Procedure
 
-First, create a dedicated namespace:
+### Step 1 - Set up your namespace
+
+Create a dedicated namespace as follows:
 
 ```bash
 kubectl create namespace petstore
 ```
 
-## Create a Persistent Volume Claim
+### Step 2 - Create a Persistent Volume Claim
 
-For this guide, to store associated Tekton build artifacts, we'll create a PVC in the `petstore` namespace:
+For this example, to store associated Tekton build artifacts, create a Persistent Volume Claim (PVC) in the `petstore` namespace as follows:
 
 ```bash
 kubectl apply -n petstore -f - <<EOF
@@ -37,9 +39,9 @@ spec:
 EOF
 ```
 
-## Define the Tekton Task
+## Step 3 - Define the Tekton Task
 
-Define the task that outlines steps to clone a repository, generate Kuadrant and Kubernetes resources using `kuadrantctl`, and apply them directly to the cluster:
+Define the task that outlines steps to clone a repository, generate Kuadrant and Kubernetes resources by using `kuadrantctl`, and apply them directly to the cluster as follows:
 
 ```bash
 kubectl apply -f - <<'EOF'
@@ -102,25 +104,25 @@ spec:
 EOF
 ```
 
-We're using Tekton here with `kubectl` to apply resources to a cluster. We recommend looking at a tool such as [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) to implement continuous delivery via a GitOps approach. In this scenario, you would:
+**Note:** This example uses Tekton with `kubectl` to apply resources to a cluster. It is best to use a tool such as [Argo CD](https://argo-cd.readthedocs.io/en/stable/) to implement continuous delivery by using a GitOps approach. In this scenario, you would do the following:
 
-- Use `kuadrantctl` to generate Kubernetes/Kuadrant resources as part a Tekton pipeline
-- Commit these new resources in to a git respository
-- Use ArgoCD to sync these changes via a Git respository to a Kubernetes or OpenShift cluster
+- Use `kuadrantctl` to generate Kubernetes and Kuadrant resources as part a Tekton pipeline.
+- Commit these new resources to a Git repository.
+- Use ArgoCD to sync these changes from the Git repository to a Kubernetes or OpenShift cluster.
 
-## Create a Kubeconfig Secret
+## Step 4 - Create a Kubeconfig secret
 
-> **Note:** Important: While this guide uses a kubeconfig secret for simplicity, it is not recommended for production environments. Instead, use a Service Account for enhanced security.
+> **Important:** While this guide uses a `kubeconfig` secret for simplicity, do not use this in production environments. Instead, use a service account for enhanced security.
 
-In this guide, we use a `kubeconfig` secret coupled with role bindings to demonstrate how to provide access for pushing generated resources to a cluster. However, for production setups, employing a Service Account is advised.
+This example uses a `kubeconfig` secret and role bindings to demonstrate how to provide access for pushing generated resources to a cluster. However, for production setups, employing a service account is best.
 
-To proceed, create a kubeconfig secret in the `petstore` namespace to provide Tekton with access to your Kubernetes cluster:
+To proceed, create a `kubeconfig` secret in the `petstore` namespace to provide Tekton with access to your Kubernetes cluster as follows:
 
 ```bash
 kubectl create secret generic kubeconfig-secret --from-file=kubeconfig=/path/to/.kube/config -n petstore
 ```
 
-Create an associated `ClusterRole` and `ClusterRoleBinding`:
+Create an associated `ClusterRole` and `ClusterRoleBinding` as follows:
 
 ```bash
 kubectl apply -n petstore -f - <<EOF
@@ -148,11 +150,11 @@ roleRef:
 EOF
 ```
 
-## Trigger the `TaskRun`
+### Step 5 - Trigger the TaskRun
 
-Execute the task within the `petstore` namespace, referencing the kubeconfig secret for cluster access:
+Execute the task from the `petstore` namespace, referencing the `kubeconfig` secret for cluster access as follows:
 
-In this example, we'll run this task with our Kuadrant Petstore app: https://github.com/kuadrant/api-petstore
+This example runs this task with the Kuadrant Petstore app: https://github.com/kuadrant/api-petstore.
 
 ```bash
 kubectl apply -n petstore -f - <<EOF
@@ -179,7 +181,7 @@ spec:
 EOF
 ```
 
-If you have `tkn` installed, you can easily view the progress of the pipe run:
+If you have `tkn` installed, you can easily view the progress of the pipe run as follows:
 
 ```bash
 tkn taskrun list -n petstore
@@ -209,12 +211,12 @@ tkn taskrun logs -n petstore -f
 [apply-resources] ratelimitpolicy.kuadrant.io/petstore created
 ```
 
-## Cleanup
+### Step 6 - Cleanup
 
-To cleanup:
+Clean up your resources as follows:
 
-- Remove the `petstore` namespace:
-- - `kubectl delete ns petstore`
-- Remove the `ClusterRole` and `ClusterRoleBinding`:
-- - `kubectl delete clusterrole kuadrant-ci-example-full-access`
-- - `kubectl delete clusterrolebinding kuadrant-ci-example-full-access-binding`
+1. Remove the `petstore` namespace:
+   - `kubectl delete ns petstore`
+2. Remove the `ClusterRole` and `ClusterRoleBinding`:
+   - `kubectl delete clusterrole kuadrant-ci-example-full-access`
+   - `kubectl delete clusterrolebinding kuadrant-ci-example-full-access-binding`

doc/openapi-kuadrant-extensions.md

@@ -1,10 +1,10 @@
 # OpenAPI 3.0.x Kuadrant extensions
 
-This reference information shows examples of how to add Kuadrant extensions at the `info`, path, and operation level in an OpenAPI 3.0.x definition. 
+This reference information shows examples of how to add Kuadrant extensions at the root, path, or operation level in an OpenAPI 3.0.x definition. 
 
-## Info-level Kuadrant extension
+## Root-level Kuadrant extension
 
-You can add a Kuadrant extension at the `info` level of an OpenAPI definition. The following example shows an extension added for a `petstore` app:
+You can add a Kuadrant extension at the root level of an OpenAPI definition. The following example shows an extension added for a `petstore` app:
 
 ```yaml
 x-kuadrant: