Improved doc formating

Signed-off-by: eyuen <[email protected]>

Author: elsony

docs/proposals/devfile/outer-loop-build-and-deploy.md

@@ -7,7 +7,7 @@ Existing devfile 2.0 mainly focuses on providing inner-loop support. This propos
 As an application developer, I would like to build a microservice and deploy it to Kubernetes to do a build that is typically done as part of a pipeline
 
 - Do a full build to build the container image
-    - Input\
+    - Input:\
     The build may use different technologies for building, e.g. dockerfile, buildpacks
     - Output:\
     A container image that contains the microservice and ready to be deployed to Kubernetes
@@ -19,7 +19,7 @@ The focus of this proposal is to provide the ability to build and deploy applica
 
 We will cover two main stages:
 1. Build the image
-2. Deployment of the image. Deploy the image to a cluster
+2. Deploy the image to a cluster
 
 ## Build the image
 
@@ -37,6 +37,7 @@ The definition of the image build introduces a new component type `image` for th
 __Alternative approach:__ we can consider reusing the `exec` type except that these build types are special and we may not want to incorporate the full image build command into an `exec` command. Therefore, I chose to use a different type of command here.
 
 ### Example using a file Dockerfile as part of the app:
+```yaml
     variables:
       myimage: myimagename
     components:
@@ -48,6 +49,7 @@ __Alternative approach:__ we can consider reusing the `exec` type except that th
             location: Dockerfile
             args: [ "arg1", "arg2", "arg3" ]
             rootRequired: false
+```
 
 `imageName`: name of the generated image (or we may use an id for referencing the image). This imageName can also be fully qualified to allow pushing of the image to a specific image registry.
 
@@ -63,6 +65,7 @@ __Note:__
 1. A common pattern will be using a global variable to define the image name (`myimage` in the example above) so that it can be easily referred to in the deploy step later.
 
 ### Example using a Dockerfile with registry and secret for the image push:
+```yaml
     variables:
       myimage: myimagename
     components:
@@ -77,18 +80,22 @@ __Note:__
             envFrom:
             - secretRef:
                 name: my-secret
+```
 
 `secretRef`: The reference to the secret for pushing the image to the registry
 
 For the secrets, it should support the same mechanisms as specified in https://github.com/devfile/api/issues/299.
 
 ### Example using `apply` command on an image component:
+```yaml
     commands:
       - id: deploybuild
         apply:
           component: mydockerfileimage
+```
 
 ### Example using a Dockerfile stored within the devfile registry as a resource with `apply` command:
+```yaml
     variables:
       myimage: myimagename
     components:
@@ -102,11 +109,13 @@ For the secrets, it should support the same mechanisms as specified in https://g
       - id: deploybuild
         apply:
           component: mydockerfileimage
+```
 
 __Note:__
 1. The `apply` command with the `image` component is optional. If the `apply` command that references an image component does not exist, then the image build will be done at the startup automatically (similar to the behaviour of the existing `kubernetes` components).  If there is an `apply` command that references the `image` component, then the user will need to create a composite command to chain the image build apply command with the deploy command (see the deployment command section) to complete the build and deploy.
 
 ### Example using a Dockerfile stored in a git repo with push registry without apply command:
+```yaml
     variables:
       myimage: myimagename
     components:
@@ -119,6 +128,7 @@ __Note:__
                 origin: "https://github.com/odo-devfiles/nodejs-ex.git"
             location: Dockerfile
             args: [ ]
+```
 
 The git definition will be the same as the one in `starterProjects` definition that supports `checkoutFrom`
 
@@ -130,6 +140,7 @@ Notes:
 1. Do we need image push registry info to specify where to push the image to? If needed, then the secret for the push can be specified as `secretKeyRef` in https://github.com/devfile/api/issues/299
 
 ### Example using SourceToImage (S2I):
+```yaml
     variables:
       myimage: myimagename
     components:
@@ -146,6 +157,7 @@ Notes:
       - id: deploybuild
       apply:
         component: mys2iimage
+```
 
 `builderImageNamespace`: Namespace where builder image is present
 
@@ -170,6 +182,7 @@ The current design is to try to reuse the existing `kubernetes` component as muc
 
 #### Examples of using `deploy` group command:
 ##### Kubernetes deployment manifest:
+```yaml
     components:
       - name: myk8sdeploy
         kubernetes:
@@ -185,12 +198,14 @@ The current design is to try to reuse the existing `kubernetes` component as muc
         attributes: 
           - name: CONTAINER_IMAGE
             value: {{myimage}}
+```
 
 `uri`: Kubernetes manifest location (can use `kubectl` to deploy) which can be an URL or a path relative to the devfile. [Example of Kubernetes deployment](#markdown-header-example-of-kubernetes-deployment-manifest) manifest and [example of Operator deployment manifest](#markdown-header-example-of-operator-deployment-manifest).
 
 Variables that need to be replaced during the deployment can be specified using a new `attributes` definition under the `apply` command. One usage example is to pass the image name along to the deployment manifest. A common practice is to use a global variable, e.g. `myimage` in the example above, to refer to the image built in the image built stage.
 
 ##### Kubernetes deployment manifest (inlined):
+```yaml
     components:
       - name: myk8deploy
         kubernetes:
@@ -215,8 +230,27 @@ Variables that need to be replaced during the deployment can be specified using
           group:
             kind: deploy
             isDefault: true
+```
+
+#### Example of Operator deployment manifest:
+```yaml
+    apiVersion: app.stacks/v1beta1
+    kind: RuntimeComponent
+    metadata:
+      name: {{.COMPONENT_NAME}}
+    spec:
+      applicationImage: {{.CONTAINER_IMAGE}}
+      service:
+        type: ClusterIP
+        port: {{.PORT}}
+      expose: true
+      storage:
+        size: 2Gi
+        mountPath: "/logs"
+```
 
 ##### Helm:
+```yaml
     components:
       - name: myhelmdeploy
         helm:
@@ -234,10 +268,11 @@ Variables that need to be replaced during the deployment can be specified using
         variables: 
           - name: CONTAINER_IMAGE
             value: {{myimage}}
-
+```
 
 ### Deployment manifest examples
 #### Example of Kubernetes deployment manifest:
+```yaml
     ---
     kind: Deployment
     apiVersion: apps/v1
@@ -290,21 +325,7 @@ Variables that need to be replaced during the deployment can be specified using
       port:
         targetPort: {{.PORT}}
       wildcardPolicy: None
+```
 
 This example is using variables for tools to replace some of the info during deployment.
 
-#### Example of Operator deployment manifest:
-
-    apiVersion: app.stacks/v1beta1
-    kind: RuntimeComponent
-    metadata:
-      name: {{.COMPONENT_NAME}}
-    spec:
-      applicationImage: {{.CONTAINER_IMAGE}}
-      service:
-        type: ClusterIP
-        port: {{.PORT}}
-      expose: true
-      storage:
-        size: 2Gi
-        mountPath: "/logs"

docs/proposals/registry/sample-vs-stack.md

@@ -2,21 +2,21 @@
 
 ## Overview
 
-The existing devfile registry focuses on the stack support to provide generic language/framework/runtime, e.g. Node, Java maven, Quarkus, etc.,  support to build and run user applications. These devfiles are called ***stack devfiles***.  There is another kind of devfile in a devfile registry that is tailored for a building and running a specific application. These devfiles are referred to as ___*sample devfiles*___ (example: https://github.com/redhat-developer/devfile-sample).
+The existing devfile registry focuses on the stack support to provide generic language/framework/runtime, e.g. Node, Java maven, Quarkus, etc.,  support to build and run user applications. These devfiles are called ***stack devfiles***.  There is another kind of devfile in a devfile registry that is tailored for a building and running a specific application. These devfiles are referred to as ***sample devfiles*** (example: https://github.com/redhat-developer/devfile-sample).
 
 This proposal covers the design to support sample devfiles as a first-class citizen and differentiates between stack vs samples so that the tools can consume them properly. Also, it allows the source of a given stack and samples to be stored under a different repository other than the main source registry repo.
 
 ## Adding samples or stacks to the devfile registry
 
-A file called ___*extraDevfileEntries.yaml*___ is added under the root of the devfile registry source repository to add samples and stacks from other repositories to the registry. This file contains the location information on where the extra samples and stacks can be found during a registry build.
+A file called ***extraDevfileEntries.yaml*** is added under the root of the devfile registry source repository to add samples and stacks from other repositories to the registry. This file contains the location information on where the extra samples and stacks can be found during a registry build.
 
 ### Sample extraDevfileEntires.yaml:
 
 __Note:___ Proposal #2 will be used
 
 #### Proposal 1 (deferred: will only implement later when needed):
 If we assume the devfile in a given sample contains the information on the sample, we can future simplify it by just referring the sample to the location. All the metadata information is extracted directly from the devfile contained in the sample/stack repository.
-
+```yaml
     schemaVersion: 1.0.0
     samples:
     - name: nodejs-basic
@@ -35,13 +35,14 @@ If we assume the devfile in a given sample contains the information on the sampl
       git:
         remotes:
           origin: https://github.com/eystacks/my-maven
+```
 
 __Note:__ the location of the sample supports the same configuration as the `starterProjects` definition, i.e. `git` and `zip`. Refer to the definitions of the existing `git` and `zip` elements for supported settings.
 
 #### Proposal 2:
 
 Alternatively, if we assume the devfile contained in the sample folder may refer to the original stack instead of the specific example, we may need to include a way for the user to specify the metadata associated with the sample as part of the sample definition.
-
+```yaml
     schemaVersion: 1.0.0
     samples:
       - name: nodejs-basic
@@ -84,6 +85,7 @@ Alternatively, if we assume the devfile contained in the sample folder may refer
         git:
           remotes:
             origin: https://github.com/elsony/devfile-sample-python-basic.git
+```
 
 #### Proposal 3: Include the source of the samples as part of the registry source repository (deferred: will only implement later when needed)
 The existing devfile registry source for the stacks have the following structure:
@@ -156,7 +158,7 @@ With the introduction of the samples in the registry, the samples will be stored
 
 ## Registry query results
 The information on the registry index (index.json) is different between a stack and a sample. The differences are based on how the two will be used.
-
+```json
     [
         {
             "name": "java-maven",
@@ -199,6 +201,7 @@ The information on the registry index (index.json) is different between a stack
             }
         }
     ]
+```
 
 The differences between a stack entry vs a sample entry in the devfile index registry are:
 1. The `type` field