Add OpenShift-specific section to the README, & spruce up docs (#182)

Signed-off-by: John Starich <[email protected]>

Makefile

@@ -168,7 +168,7 @@ out:
 release-prep: kustomize out 
 	cd config/manager && kustomize edit set image controller=${IMG}
 	kustomize build config/default --output out/
+	go run ./internal/cmd/genolm --version ${RELEASE_VERSION}
 
 .PHONY: release
 release: release-prep docker-push
-	go run ./internal/cmd/genolm --version ${RELEASE_VERSION}

README.md

@@ -1,10 +1,11 @@
-
 [![Build Status](https://travis-ci.com/IBM/cloud-operators.svg?branch=master)](https://travis-ci.com/IBM/cloud-operators)
 [![Go Report Card](https://goreportcard.com/badge/github.com/IBM/cloud-operators)](https://goreportcard.com/report/github.com/IBM/cloud-operators)
 [![GoDoc](https://godoc.org/github.com/IBM/cloud-operators?status.svg)](https://godoc.org/github.com/IBM/cloud-operators)
 
 # IBM Cloud Operator
 
+<!-- SHOW operator hub -->
+
 The IBM Cloud Operator provides a simple Kubernetes CRD-Based API to provision and bind 
 IBM public cloud services on your Kubernetes cluster. With this operator, you no longer need
 out-of-band processes to consume IBM Cloud Services in your application; 
@@ -48,36 +49,69 @@ ibmcloud target -g <resource-group>
 
 Notice that the `org` and `space` must be included, even if no Cloud Foundry services will be instantiated.
 
-## Installing the operator
+## Set up the operator
+
+To set up the operator after logging in with `ibmcloud`, run the below installer.
+
+By default, the script will create a new API key for use in the operator. To use a custom API key, set the `IBMCLOUD_API_KEY` environment variable to the key.
+
+#### Using a ServiceId
+
+To instantiate services and bindings on behalf of a ServiceId, set the environment variable `IBMCLOUD_API_KEY` to the `api-key` of the ServiceId. This can be obtained via the IBM Cloud Console or [CLI](https://cloud.ibm.com/docs/iam?topic=iam-serviceids). Be sure to give proper access permissions to the ServiceId.
+
+Next log into the IBM Cloud account that owns the ServiceId and follow the instructions above.
+
+<!-- END SHOW operator hub -->
+
+### Install
 
 To install the latest release of the operator, run the following script:
 
 ```bash
 curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash 
 ```
 
-The script above first creates an IBM Cloud API Key and stores it in a Kubernetes secret that can be
-accessed by the operator, then it sets defaults such as the default resource group and region 
-used to provision IBM Cloud Services; finally, it deploys the operator in your cluster. You can always override the defaults in the `Service` custom resource. If you prefer to create the secret and the defaults manually, consult the [IBM Cloud Operator documentation](docs/install.md).
+The above script stores an API key in a Kubernetes secret that can be accessed by the operator.
+Next, it sets default values used in provisioning IBM Cloud Services, like the resource group and region.
+You can override any default value in the `Service` custom resource.
+Finally, the script deploys the operator in your cluster.
+
+If you prefer to create the secret and the defaults manually, consult the [IBM Cloud Operator documentation](docs/install.md).
 
 To install a specific version of the operator, you can pass a semantic version:
 
 ```bash
 curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash -s -- -v 0.0.0
 ```
 
-### Using a ServiceId
+### Uninstall
 
-To instantiate services and bindings on behalf of a ServiceId, set the environment variable `IC_APIKEY` to the `api-key` of the ServiceId. This can be obtained via the IBM Cloud Console or [CLI](https://cloud.ibm.com/docs/iam?topic=iam-serviceids). Be sure to give proper access permissions to the ServiceId.
+To remove the operator, run the following script:
 
-Next log into the IBM Cloud account that owns the ServiceId and follow the instructions above.
+```bash
+curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash -s -- delete
+```
 
-## Removing the operator
+<!-- SHOW operator hub -->
 
-To remove the operator, run the following script:
+### Configure the operator for OpenShift
+
+To configure the latest release for OpenShift before install, run the following script:
 
 ```bash
-curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash -s -- delete
+curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash -s -- store-creds
+```
+
+The above script stores an API key in a Kubernetes secret that can be accessed by the operator.
+Next, it sets default values used in provisioning IBM Cloud Services, like the resource group and region.
+You can override any default value in the `Service` custom resource.
+
+If you prefer to create the secret and the defaults manually, consult the [IBM Cloud Operator documentation](docs/install.md).
+
+To configure with a specific version of the operator, you can pass a semantic version:
+
+```bash
+curl -sL https://raw.githubusercontent.com/IBM/cloud-operators/master/hack/configure-operator.sh | bash -s -- -v 0.0.0 store-creds
 ```
 
 ## Using the IBM Cloud Operator
@@ -147,6 +181,8 @@ mybinding                  Opaque                                6      102s
 You can find [additional samples](config/samples), and more information on 
 [using the operator](docs/user-guide.md) in the operator documentation.
 
+<!-- END SHOW operator hub -->
+
 ### Service Properties
 
 A `Service` includes the following properties:

config/manager/kustomization.yaml

@@ -5,4 +5,4 @@ kind: Kustomization
 images:
 - name: controller
   newName: cloudoperators/ibmcloud-operator
-  newTag: 0.0.0
+  newTag: 0.2.1

internal/cmd/genolm/readme.go

@@ -12,20 +12,34 @@ import (
 
 func prepREADME(readme io.Reader) string {
 	scanner := bufio.NewScanner(readme)
-	include := false
+	showing := false
+	codeFence := false
 	var buf bytes.Buffer
 	for scanner.Scan() {
 		line := scanner.Text()
 		line = convertToAbsoluteLinks(line)
 
-		if include {
-			if line != "" || buf.Len() > 0 { // skip leading blank lines
+		switch {
+		case strings.HasPrefix(line, `<!-- SHOW `) && strings.HasSuffix(line, ` -->`):
+			showing = true
+		case strings.HasPrefix(line, `<!-- END SHOW `) && strings.HasSuffix(line, ` -->`):
+			showing = false
+		case line == "" && buf.Len() == 0: // skip leading blank lines
+		case showing:
+			const codeFenceStr = "```"
+			switch {
+			case codeFence && strings.HasPrefix(line, codeFenceStr):
+				codeFence = false
+			case strings.HasPrefix(line, codeFenceStr):
+				codeFence = true
+			case codeFence:
+				buf.WriteString("    ") // indent code line
+				buf.WriteString(line)
+				buf.WriteRune('\n')
+			default:
 				buf.WriteString(line)
 				buf.WriteRune('\n')
 			}
-		} else if strings.HasPrefix(line, "# ") {
-			// skip up to and including main header lines
-			include = true
 		}
 	}
 	if err := scanner.Err(); err != nil {