doc/sdk-cli-reference: update for [api,controller], cleanup for [new,generate] (#674)

- Added the CLI reference description and examples for `add api` and `add controller`
- Cleaned up the section for `new` by making the flags `--api-version` and `--kind` only specific to `--type=ansible`. Also added the example cmd for ansible.
- Made the description for `generate k8s` more specific. The example output was outdated as well.
- The doc for `generate crd` was wrong. It's actually `add crd` so I moved it down to the correct section. The example was outdated too since the filenames changed after the refactor.
- Removed the section for `generate olm-catalog` since we no longer have that in our CLI.

Author: hasbro17

doc/sdk-cli-reference.md

@@ -90,100 +90,125 @@ operator-sdk completion bash
 
 ## generate
 
-### Available Commands
-
-#### k8s - Generates Kubernetes code for custom resource
+### k8s 
 
-##### Use
+Runs the Kubernetes [code-generators][k8s-code-generator] for all Custom Resource Definitions (CRD) apis under `pkg/apis/...`.
+Currently only runs `deepcopy-gen` to generate the required `DeepCopy()` functions for all custom resource types.
 
-k8s generator generates code for custom resource given the API spec
-to comply with kube-API requirements.
+**Note**: This command must be run every time the api (spec and status) for a custom resource type is updated.
 
-##### Flags
-
-* `-h, --help` - help for k8s
-
-##### Example
+#### Example
 
 ```bash
-operator-sdk generate k8s
-
-# Output:
-Run code-generation for custom resources
+$ tree pkg/apis/app/v1alpha1/
+pkg/apis/app/v1alpha1/
+├── appservice_types.go
+├── doc.go
+├── register.go
+
+$ operator-sdk generate k8s
+Running code-generation for custom resource group versions: [app:v1alpha1]
 Generating deepcopy funcs
+
+$ tree pkg/apis/app/v1alpha1/
+pkg/apis/app/v1alpha1/
+├── appservice_types.go
+├── doc.go
+├── register.go
+└── zz_generated.deepcopy.go
 ```
 
-#### crd - Generates a custom resource definition (CRD) and the custom resource (CR) files
+## new
 
-##### Use
+Scaffolds a new operator project.
 
-crd generator generates custom resource definition and custom resource
-files for the specified api-version and kind.
+### Args
 
-##### Flags
+* `project-name` - name of the new project
 
-* `--api-version` **(required)** string - Kubernetes apiVersion and has a format of $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
-* `-h, --help` - help for k8s
-* `--kind` **(required)** string - Kubernetes CustomResourceDefinition kind. (e.g AppService)
+### Flags
 
-##### Example
 
+* `--skip-git-init` Do not init the directory as a git repository
+* `--type` Type of operator to initialize: "ansible" or "go" (default "go"). Also requires the following flags if `--type=ansible`
+  * `--api-version` CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1)
+  * `--kind` CRD Kind. (e.g AppService)
+* `-h, --help` - help for new
+
+### Example
+
+Go project:
 ```bash
-operator-sdk generate crd --api-version app.example.com/v1alpha1 --kind AppService
+mkdir $GOPATH/src/github.com/example.com/
+cd $GOPATH/src/github.com/example.com/
+operator-sdk new app-operator
+```
 
-# Output:
-Generating custom resource definition (CRD) file
-Create <path_to_project>/deploy/appservice_cr.yaml
-Create <path_to_project>/deploy/appservice_crd.yaml
+Ansible project:
+```bash
+operator-sdk new app-operator --type=ansible --api-version=app.example.com/v1alpha1 --kind=AppService
 ```
-#### olm-catalog - Generates OLM Catalog manifests
 
-##### Flags
+## add
 
-* `--image` **(required)** string - The container image name to set in the CSV to deploy the operator e.g: quay.io/example/operator:v0.0.1
-* `--version` **(required)** string - The version of the current CSV e.g: 0.0.1
-* `-h, --help` - help for olm-catalog
+### api
 
-##### Example
+Adds the
+api definition for a new custom resource under `pkg/apis` and generates the CRD and CR files under `depoy/crds/...`.
 
-```bash
-operator-sdk generate olm-catalog --image=quay.io/example/operator:v0.0.1 --version=0.0.1
+#### Flags
 
-# Output:
-Generating OLM catalog manifests
+* `--api-version` CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1)
+* `--kind` CRD Kind. (e.g AppService)
+
+#### Example
+
+```bash
+$ operator-sdk add api --api-version app.example.com/v1alpha1 --kind AppService
+Create pkg/apis/app/v1alpha1/appservice_types.go
+Create pkg/apis/addtoscheme_app_v1alpha1.go
+Create pkg/apis/app/v1alpha1/register.go
+Create pkg/apis/app/v1alpha1/doc.go
+Create deploy/crds/app_v1alpha1_appservice_cr.yaml
+Create deploy/crds/app_v1alpha1_appservice_crd.yaml
+Running code-generation for custom resource group versions: [app:v1alpha1]
+Generating deepcopy funcs
 ```
 
-### Flags
+### controller
 
-* `-h, --help` - help for generate
+Adds a new
+controller under `pkg/controller/<kind>/...` that, by default, reconciles a custom resource for the specified apiversion and kind.
 
-## new
+#### Flags
 
-The operator-sdk new command creates a new operator application and
-generates a default directory layout based on the input `project-name`.
+* `--api-version` CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1)
+* `--kind` CRD Kind. (e.g AppService)
 
-### Args
+#### Example
 
-* `project-name` - the project name of the new
+```bash
+$ operator-sdk add controller --api-version app.example.com/v1alpha1 --kind AppService
+Create pkg/controller/appservice/appservice_controller.go
+Create pkg/controller/add_appservice.go
+```
 
-### Flags
+### crd
 
-* `--api-version` **(required)** string - Kubernetes apiVersion and has a format of `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1)
-* `--kind` **(required)** string - Kubernetes CustomResourceDefintion kind. (e.g AppService)
-* `--skip-git-init` Do not init the directory as a git repository
-* `--type` Type of operator to initialize (e.g "ansible") (default "go")
-* `-h, --help` - help for new
+Generates the CRD and the CR files for the specified api-version and kind.
 
-### Example
+#### Flags
 
-```bash
-mkdir $GOPATH/src/github.com/example.com/
-cd $GOPATH/src/github.com/example.com/
-operator-sdk new app-operator --api-version=app.example.com/v1alpha1 --kind=AppService
+* `--api-version` CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1)
+* `--kind` CRD Kind. (e.g AppService)
 
-# Output:
-Create app-operator/.gitignore
-...
+#### Example
+
+```bash
+$ operator-sdk add crd --api-version app.example.com/v1alpha1 --kind AppService
+Generating custom resource definition (CRD) files
+Create deploy/crds/app_v1alpha1_appservice_crd.yaml
+Create deploy/crds/app_v1alpha1_appservice_cr.yaml
 ```
 
 ## test
@@ -293,3 +318,4 @@ operator-sdk up local --namespace "testing"
 * `-h, --help` - help for up
 
 [utility_link]: https://github.com/operator-framework/operator-sdk/blob/89bf021063d18b6769bdc551ed08fc37027939d5/pkg/util/k8sutil/k8sutil.go#L140
+[k8s-code-generator]: https://github.com/kubernetes/code-generator