Reorganize README, fix formatting

README.md

@@ -10,6 +10,10 @@
 
 **Accelerate the development of Kubernetes Operators.**
 
+Operator Builder is a command line tool that ingests Kubernetes manifests and
+generates the source code for a working Kubernetes operator based on the
+resources defined in those manifests.
+
 Operator Builder extends [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder)
 to facilitate development and maintenance of Kubernetes operators.  It is especially
 helpful if you need to take large numbers of resources defined with static or
@@ -31,26 +35,20 @@ The custom resource defined in the source code can be cluster-scoped or
 namespace-scoped based on the requirements of the project.  More info
 [here](docs/resource-scope.md).
 
-## Installation
-
-See our [installation options](docs/installation.md)
-
-## Getting Started
-
-Follow our [getting started guide](docs/getting-started.md)
-
-## Workload Collections
-
-Operator Builder can generate source code for operators that manage multiple
-related and dependent workloads.  See [workload collections](docs/workload-collections.md)
-for more info.
-
-## Licensing
+User Documentation:
 
-Operator Builder can help manage licensing for the resulting project.  More
-info [here](docs/license.md).
+* [Installation](docs/installation.md)
+* [Getting Started](docs/getting-started.md)
+* [Workloads](docs/workloads.md)
+* [Standalone Workloads](docs/standalone-workloads.md)
+* [Workload Collections](docs/workload-collections.md)
+* [Markers](docs/markers.md)
+* [Resource Scope](docs/resource-scope.md)
+* [Companion CLI](docs/companion-cli.md)
+* [API Updates & Upgrades](docs/api-updates-upgrades.md)
+* [License Manaagement](docs/license.md)
 
-## Testing
+Develpoer Documentation
 
-Testing of Operator Builder is documented [here](docs/testing.md).
+* [Testing](docs/testing.md)
 

docs/api-updates-upgrades.md

@@ -18,11 +18,13 @@ describe how to overwrite an existing API to update the existing spec.
 
 After making the necessary changes to your manifests run the following:
 
-    operator-builder create api \
-        --workload-config [path/to/workload/config] \
-        --controller=false \
-        --resource \
-        --force
+```bash
+operator-builder create api \
+    --workload-config [path/to/workload/config] \
+    --controller=false \
+    --resource \
+    --force
+```
 
 You will pass the same workload config file.  The `--controller=false` flag will
 skip generating controller code but `--resource` and `--force` will cause the
@@ -111,7 +113,7 @@ the software when other features not related to an API are released.
 To create a new version of an existing API, update the `spec.api.version` value
 in your workload config, for example:
 
-```
+```yaml
 name: webstore
 kind: StandaloneWorkload
 spec:
@@ -130,11 +132,13 @@ spec:
 
 Now reference the config in a new `create api` command:
 
-    operator-builder create api \
-        --workload-config [path/to/workload/config] \
-        --controller \
-        --resource \
-        --force
+```bash
+operator-builder create api \
+    --workload-config [path/to/workload/config] \
+    --controller \
+    --resource \
+    --force
+```
 
 Note that we _do_ want to re-generate the controller in this case.
 A new API definition will be create alongside the previous version.  If the
@@ -143,24 +147,26 @@ version.
 
 For example if your APIs look as follows:
 
-    tree apis/apps
-    apis/apps
-    ├── v1alpha1
-    │   ├── groupversion_info.go
-    │   ├── webstore
-    │   │   ├── app.go
-    │   │   └── resources.go
-    │   ├── webstore_types.go
-    │   └── zz_generated.deepcopy.go
-    └── v1alpha2
-        ├── groupversion_info.go
-        ├── webstore
-        │   ├── app.go
-        │   └── resources.go
-        ├── webstore_types.go
-        └── zz_generated.deepcopy.go
-
-    4 directories, 10 files
+```bash
+tree apis/apps
+apis/apps
+├── v1alpha1
+│   ├── groupversion_info.go
+│   ├── webstore
+│   │   ├── app.go
+│   │   └── resources.go
+│   ├── webstore_types.go
+│   └── zz_generated.deepcopy.go
+└── v1alpha2
+    ├── groupversion_info.go
+    ├── webstore
+    │   ├── app.go
+    │   └── resources.go
+    ├── webstore_types.go
+    └── zz_generated.deepcopy.go
+
+4 directories, 10 files
+```
 
 You will delete the earlier version with `rm -rf apis/apps/v1alpha1`.
 

docs/companion-cli.md

@@ -1,6 +1,8 @@
 # Companion CLI
 
-Generate source code for a companion CLI to a Kubernetes operator.
+When you generate the source code for a Kubernetes operator with Operator
+Builder, it can include the code for a companion CLI.  The source code for the
+companion CLI will be found in the `cmd` directory of the generated codebase.
 
 The companion CLI does three things:
 1. Generate Sample Manifests: the `init` command will save a sample manifest to