Adjust admonition formatting in the Upgrade an Extension doc

This should improve overall legibility of the doc and encapsulates each example into discrete sections/admonitions. Signed-off-by: Tayler Geiger <[email protected]>
operator-framework · Nov 19, 2024 · e20b9e2 · e20b9e2
1 parent 4ad1715
commit e20b9e2
Showing 1 changed file with 31 additions and 28 deletions.
diff --git a/docs/tutorials/upgrade-extension.md b/docs/tutorials/upgrade-extension.md
@@ -25,7 +25,7 @@ For this example, we will be using v0.2.0 of the ArgoCD operator. If you would l
 with this tutorial, you can apply the following manifest to your cluster by, for example,
 saving it to a local file and then running `kubectl apply -f FILENAME`:
 
-??? example "ArgoCD v0.2.0 manifests"
+??? info "ArgoCD v0.2.0 manifests"
     ```yaml
     ---
     apiVersion: v1
@@ -300,14 +300,17 @@ saving it to a local file and then running `kubectl apply -f FILENAME`:
           version: 0.2.0
     ```
 
+___
+
 If we view the current state of our ClusterExtension we should see that we have installed version 0.2.0:
 
-```terminal
-kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
-```
+!!! example "How to check the current ClusterExtension version"
 
-!!! success "Command output"
-    ``` json
+    ```terminal title="Get current version"
+    kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
+    ```
+
+    ``` json title="Version output"
     [
         {
             "bundle": {
@@ -318,9 +321,11 @@ kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
     ]
     ```
 
-* To initiate our upgrade, let's update the version field in the ClusterExtension resource:
+To initiate our upgrade, let's update the version field in the ClusterExtension resource:
 
-    ``` terminal
+!!! example "How to set the new ClusterExtension version"
+
+    ``` terminal title="Method 1: apply a new ClusterExtension manifest"
     kubectl apply -f - <<EOF
     apiVersion: olm.operatorframework.io/v1
     kind: ClusterExtension
@@ -338,39 +343,37 @@ kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
     EOF
     ```
 
-    !!! success "Command output"
-        ``` text
-        clusterextension.olm.operatorframework.io/argocd configured
-        ```
+    ``` text title="Method 1 output"
+    clusterextension.olm.operatorframework.io/argocd configured
+    ```
 
     Alternatively, you can use `kubectl patch` to update the version field:
 
-    ``` terminal
+    ``` terminal title="Method 2: run patch command"
     kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}'
     ```
 
-    !!! success "Command output"
-        ``` text
-        clusterextension.olm.operatorframework.io/argocd patched
-        ```
+    ``` text title="Method 2 output"
+    clusterextension.olm.operatorframework.io/argocd patched
+    ```
 
-* Verify that the Kubernetes extension is updated:
+We can now verify that the ClusterExtension is updated to the new version:
 
+!!! example "How to verify the new ClusterExtension version"
     ``` terminal
     kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
     ```
 
-    !!! success "Updated ClusterExtension version"
-        ``` json
-        [
-            {
-                "bundle": {
-                    "name": "argocd-operator.v0.2.1",
-                    "version": "0.2.1"
-                }
+    ``` json
+    [
+        {
+            "bundle": {
+                "name": "argocd-operator.v0.2.1",
+                "version": "0.2.1"
             }
-        ]
-        ```
+        }
+    ]
+    ```
 
 !!! note "Note on the `kubectl.kubernetes.io/last-applied-configuration` annotation"
     After your upgrade, the contents of the `kubectl.kubernetes.io/last-applied-configuration` annotation field will