Update README

Signed-off-by: Dale Haiducek <[email protected]>

Author: dhaiducek

README.md

@@ -6,65 +6,84 @@ The Policy Generator constructs Open Cluster Management policies from Kubernetes
 PolicyGenerator Custom Resource. The Policy Generator is a binary compiled for use as a
 [kustomize](https://kustomize.io/) exec plugin.
 
+- [Installing the Policy Generator](#installing-the-policy-generator)
+  - [Prerequisite](#prerequisite)
+  - [Install the binary](#install-the-binary)
+    - [Download a released version](#download-a-released-version)
+    - [Using `go install` (available for `v1.11.0` and higher)](#using-go-install-available-for-v1110-and-higher)
+    - [Build from source](#build-from-source)
+- [Using the Policy Generator](#using-the-policy-generator)
+  - [As a Kustomize plugin](#as-a-kustomize-plugin)
+  - [As a standalone binary](#as-a-standalone-binary)
+- [Additional Policy Generator references](#additional-policy-generator-references)
+
 For more about Open Cluster Management and its Policy Framework:
 
 - [Open Cluster Management website](https://open-cluster-management.io/)
 - [Governance Policy Framework](https://open-cluster-management.io/getting-started/integration/policy-framework/)
 - [Policy Collection repository](https://github.com/open-cluster-management-io/policy-collection)
 
-## Using the Policy Generator
+## Install the Policy Generator
 
-### As a Kustomize plugin
+### Prerequisite
 
-#### Install from the GitHub release
+Create the plugin directory (optional if using the generator without Kustomize):
 
-1. Create the plugin directory:
+```bash
+mkdir -p ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator
+```
 
-   ```bash
-   mkdir -p ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator
-   ```
+**NOTE:** The default directory for Kustomize plugins is `${HOME}/.config/kustomize/plugin/`, which is used directly in
+this readme. You can change this by exporting `KUSTOMIZE_PLUGIN_HOME` to a different path and updating the root of the
+paths used in this document.
 
-2. Install the binary. You can either:
+### Install the binary
 
-   - Download a released version:
+#### Download a released version
 
-     1. Download the precompiled plugin binary from the
-        [release](https://github.com/open-cluster-management-io/policy-generator-plugin/releases) of your choice.
+1. Download the precompiled plugin binary from the
+   [release](https://github.com/open-cluster-management-io/policy-generator-plugin/releases) of your choice.
 
-     2. Move the binary to the plugin directory:
+2. Make the binary executable and move the binary to the plugin directory:
 
-        - Linux:
+   - Linux:
 
-          ```bash
-          chmod +x linux-amd64-PolicyGenerator
-          mv linux-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
-          ```
+     ```bash
+     chmod +x linux-amd64-PolicyGenerator
+     mv linux-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
+     ```
 
-        - MacOS:
+   - MacOS:
+     ```bash
+     chmod +x darwin-amd64-PolicyGenerator
+     mv darwin-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
+     ```
 
-          ```bash
-          chmod +x darwin-amd64-PolicyGenerator
-          mv darwin-amd64-PolicyGenerator ${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator
-          ```
+#### Use `go install` (available for `v1.11.0` and higher)
 
-   - Use `go install` (available for `v1.11.0` and higher):
+Set the `GOBIN` to the plugin directory and specify the desired version (this command uses `latest`):
 
-     - Set the `GOBIN` to the plugin directory and specify the desired version (this command uses `latest`):
-       ```bash
-       GOBIN=${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator \
-       go install open-cluster-management.io/policy-generator-plugin/cmd/PolicyGenerator@latest
-       ```
+```bash
+GOBIN=${HOME}/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator \
+go install open-cluster-management.io/policy-generator-plugin/cmd/PolicyGenerator@latest
+```
 
-#### Build and install from source
+#### Build from source
 
-1. Build the plugin binary (only needed once or to update the plugin):
-   ```bash
-   make build
-   ```
-   **NOTE:** This will default to placing the binary in `${HOME}/.config/kustomize/plugin/`. You can change this by
-   exporting `KUSTOMIZE_PLUGIN_HOME` to a different path.
+```bash
+make build
+```
+
+**NOTE:**
+
+- This defaults to placing the binary in the Kustomize default plugin directory `${HOME}/.config/kustomize/plugin/`. You
+  can change this by exporting `KUSTOMIZE_PLUGIN_HOME` to a different path.
+- Alternatively, you can run `make build-binary` to place the binary at the root of the repository and either use it
+  directly from there or move it to the plugin directory to use with Kustomize.
+
+## Using the Policy Generator
 
-#### Configuration
+### As a Kustomize plugin
 
 1. Create a `kustomization.yaml` file that points to `PolicyGenerator` manifest(s), with any additional desired patches
    or customizations (see [`examples/policyGenerator.yaml`](./examples/policyGenerator.yaml) for an example):
@@ -74,44 +93,35 @@ For more about Open Cluster Management and its Policy Framework:
      - path/to/generator/file.yaml
    ```
 
-   - To read more about the `PolicyGenerator` YAML, see [About the PolicyGenerator plugin](./docs/policygenerator.md)
+   - To read more about the `PolicyGenerator` YAML structure, see the
+     [Policy Generator reference YAML](./docs/policygenerator-reference.yaml)
 
-2. To use the plugin to generate policies, do one of:
-   - Utilize the `examples/` directory in this repository (the directory can be modified by exporting a new path to
-     `SOURCE_DIR`):
-     ```bash
-     make generate
-     ```
-   - From any directory with a `kustomization.yaml` file pointing to `PolicyGenerator` manifests:
-     ```bash
-     kustomize build --enable-alpha-plugins
-     ```
+2. To use the plugin to generate policies, run the Kustomize build command from any directory with a
+   `kustomization.yaml` file pointing to `PolicyGenerator` manifests:
+   ```bash
+   kustomize build --enable-alpha-plugins
+   ```
 
 ### As a standalone binary
 
-In order to bypass Kustomize and run the generator binary directly:
+In order to bypass Kustomize and run the generator binary directly, change to the directory of PolicyGenerator
+manifest(s) and run the binary with the manifest(s) as the input arguments:
 
-1. Get the binary. You can either:
+```bash
+path/to/PolicyGenerator <path/to/file/1> ... <path/to/file/n>
+```
 
-   - Build from source:
+For example:
 
-     ```bash
-     make build-binary
-     ```
+```bash
+make build-binary # This places the binary at the root of the repo, so this is optional if it was done previously
+cd examples
+../PolicyGenerator policyGenerator.yaml
+```
 
-   - Use `go install` (available for `v1.11.0` and higher):
+**NOTE:** To print the trace in the case of an error, you can add the `--debug` flag to the arguments.
 
-     ```bash
-     go install open-cluster-management.io/policy-generator-plugin/cmd/PolicyGenerator@latest
-     ```
+## Additional Policy Generator references
 
-2. Run the binary from the location of the PolicyGenerator manifest(s):
-   ```bash
-   path/to/PolicyGenerator <path/to/file/1> ... <path/to/file/n>
-   ```
-   - For example:
-     ```bash
-     cd examples
-     ../PolicyGenerator policyGenerator.yaml
-     ```
-     **NOTE:** To print the trace in the case of an error, you can add the `--debug` flag to the arguments.
+- [Policy Generator reference YAML](./docs/policygenerator-reference.yaml)
+- [Policy Generator technical documentation](./docs/policygenerator.md)