hack/doc: Autogen CLI Documentation (#2099)

* init structure

* makefile updates, compiling

* working file tree

* updated dir

* initial draft of generated docs

* update changelog

* go mod tidy

* add hugo headers to docs

* fix md block tree formatting

* remove header logic

* updated docs

* add sanity test

* add script

* update path

* path re-fix

* tidy

* mod tidy

* updated docs

* changlog command update

* Update hack/doc/gen-cli-doc.go

Co-Authored-By: Eric Stroczynski <[email protected]>

* Update hack/doc/gen-cli-doc.go

Co-Authored-By: Eric Stroczynski <[email protected]>

* Update hack/doc/gen-cli-doc.go

Co-Authored-By: Eric Stroczynski <[email protected]>

* format nits

* fmt fix

Author: Ish Shah

CHANGELOG.md

@@ -18,6 +18,7 @@
 
 - Added `Operator Version: X.Y.Z` information in the operator logs.([#1953](https://github.com/operator-framework/operator-sdk/pull/1953))
 - Make Ansible verbosity configurable via the `ansible-verbosity` flag. ([#2087](https://github.com/operator-framework/operator-sdk/pull/2087))
+- Autogenerate CLI documentation via `make cli-doc` ([#2099](https://github.com/operator-framework/operator-sdk/pull/2099))
 
 ### Changed
 

Makefile

@@ -43,7 +43,7 @@ help: ## Show this help screen
 all: format test build/operator-sdk ## Test and Build the Operator SDK
 
 # Code management.
-.PHONY: test format tidy clean
+.PHONY: format tidy clean cli-doc
 
 format: ## Format the source code
 	$(Q)go fmt $(PKGS)
@@ -54,6 +54,9 @@ tidy: ## Update dependencies
 clean: ## Clean up the build artifacts
 	$(Q)rm -rf build
 
+cli-doc: ## Generate CLI Documentation
+	./hack/doc/gen_cli_doc.sh
+
 # Build/install/release the SDK.
 .PHONY: install release_builds release
 

cmd/operator-sdk/add/api.go

@@ -55,6 +55,7 @@ is generated as a 'validation' object. Generation can be disabled with the
 --skip-generation flag.
 
 Example:
+
 	$ operator-sdk add api --api-version=app.example.com/v1alpha1 --kind=AppService
 	$ tree pkg/apis
 	pkg/apis/

cmd/operator-sdk/add/controller.go

@@ -39,6 +39,7 @@ This command must be run from the project root directory.
 If the controller pkg for that Kind already exists at pkg/controller/<kind> then the command will not overwrite and return an error.
 
 Example:
+
 	$ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService
 	$ tree pkg/controller
 	pkg/controller/

cmd/operator-sdk/build/cmd.go

@@ -48,6 +48,7 @@ This image will be automatically set in the deployment manifests.
 After build completes, the image would be built locally in docker. Then it needs to
 be pushed to remote registry.
 For example:
+
 	$ operator-sdk build quay.io/example/operator:v0.0.1
 	$ docker push quay.io/example/operator:v0.0.1
 `,

cmd/operator-sdk/cli/cli.go

@@ -0,0 +1,126 @@
+// Copyright 2019 The Operator-SDK Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+
+	// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
+	// to ensure that `run` and `up local` can make use of them.
+	_ "k8s.io/client-go/plugin/pkg/client/auth"
+
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/add"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/alpha"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/build"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/completion"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/generate"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/migrate"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/new"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/olmcatalog"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/printdeps"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/run"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/scorecard"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/test"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/up"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/version"
+	"github.com/operator-framework/operator-sdk/internal/flags"
+	"github.com/operator-framework/operator-sdk/internal/util/projutil"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+)
+
+// GetCLIRoot is intended to creeate the base command structure for the OSDK for use in CLI and documentation
+func GetCLIRoot() *cobra.Command {
+	root := &cobra.Command{
+		Use:   "operator-sdk",
+		Short: "An SDK for building operators with ease",
+		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			if viper.GetBool(flags.VerboseOpt) {
+				if err := projutil.SetGoVerbose(); err != nil {
+					log.Fatalf("Could not set GOFLAGS: (%v)", err)
+				}
+				log.SetLevel(log.DebugLevel)
+				log.Debug("Debug logging is set")
+			}
+			if err := checkGoModulesForCmd(cmd); err != nil {
+				log.Fatal(err)
+			}
+		},
+	}
+
+	root.AddCommand(add.NewCmd())
+	root.AddCommand(alpha.NewCmd())
+	root.AddCommand(build.NewCmd())
+	root.AddCommand(completion.NewCmd())
+	root.AddCommand(generate.NewCmd())
+	root.AddCommand(migrate.NewCmd())
+	root.AddCommand(new.NewCmd())
+	root.AddCommand(olmcatalog.NewCmd())
+	root.AddCommand(printdeps.NewCmd())
+	root.AddCommand(run.NewCmd())
+	root.AddCommand(scorecard.NewCmd())
+	root.AddCommand(test.NewCmd())
+	root.AddCommand(up.NewCmd())
+	root.AddCommand(version.NewCmd())
+
+	return root
+}
+
+func checkGoModulesForCmd(cmd *cobra.Command) (err error) {
+	// Certain commands are able to be run anywhere or handle this check
+	// differently in their CLI code.
+	if skipCheckForCmd(cmd) {
+		return nil
+	}
+	// Do not perform this check if the project is non-Go, as they will not
+	// be using go modules.
+	if !projutil.IsOperatorGo() {
+		return nil
+	}
+	// Do not perform a go modules check if the working directory is not in
+	// the project root, as some sub-commands might not require project root.
+	// Individual subcommands will perform this check as needed.
+	if err := projutil.CheckProjectRoot(); err != nil {
+		return nil
+	}
+
+	return projutil.CheckGoModules()
+}
+
+var commandsToSkip = map[string]struct{}{
+	"new":          struct{}{}, // Handles this logic in cmd/operator-sdk/new
+	"migrate":      struct{}{}, // Handles this logic in cmd/operator-sdk/migrate
+	"operator-sdk": struct{}{}, // Alias for "help"
+	"help":         struct{}{},
+	"completion":   struct{}{},
+	"version":      struct{}{},
+	"print-deps":   struct{}{}, // Does not require this logic
+}
+
+func skipCheckForCmd(cmd *cobra.Command) (skip bool) {
+	if _, ok := commandsToSkip[cmd.Name()]; ok {
+		return true
+	}
+	cmd.VisitParents(func(pc *cobra.Command) {
+		if _, ok := commandsToSkip[pc.Name()]; ok {
+			// The bare "operator-sdk" command will be checked above.
+			if pc.Name() != "operator-sdk" {
+				skip = true
+			}
+		}
+	})
+	return skip
+}

cmd/operator-sdk/generate/k8s.go

@@ -32,6 +32,7 @@ specs in pkg/apis/<group>/<version> directories to comply with kube-API
 requirements. Go code is generated under
 pkg/apis/<group>/<version>/zz_generated.deepcopy.go.
 Example:
+
 	$ operator-sdk generate k8s
 	$ tree pkg/apis
 	pkg/apis/

cmd/operator-sdk/generate/openapi.go

@@ -33,6 +33,7 @@ deploy/crds/<full group>_<resource>_crd.yaml; OpenAPI V3 validation YAML
 is generated as a 'validation' object.
 
 Example:
+
 	$ operator-sdk generate openapi
 	$ tree pkg/apis
 	pkg/apis/

cmd/operator-sdk/main.go

@@ -21,60 +21,15 @@ import (
 	// to ensure that `run` and `up local` can make use of them.
 	_ "k8s.io/client-go/plugin/pkg/client/auth"
 
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/add"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/alpha"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/build"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/completion"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/generate"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/migrate"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/new"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/olmcatalog"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/printdeps"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/run"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/scorecard"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/test"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/up"
-	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/version"
+	"github.com/operator-framework/operator-sdk/cmd/operator-sdk/cli"
 	"github.com/operator-framework/operator-sdk/internal/flags"
-	"github.com/operator-framework/operator-sdk/internal/util/projutil"
 
 	log "github.com/sirupsen/logrus"
-	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 )
 
 func main() {
-	root := &cobra.Command{
-		Use:   "operator-sdk",
-		Short: "An SDK for building operators with ease",
-		PersistentPreRun: func(cmd *cobra.Command, args []string) {
-			if viper.GetBool(flags.VerboseOpt) {
-				if err := projutil.SetGoVerbose(); err != nil {
-					log.Fatalf("Could not set GOFLAGS: (%v)", err)
-				}
-				log.SetLevel(log.DebugLevel)
-				log.Debug("Debug logging is set")
-			}
-			if err := checkGoModulesForCmd(cmd); err != nil {
-				log.Fatal(err)
-			}
-		},
-	}
-
-	root.AddCommand(add.NewCmd())
-	root.AddCommand(alpha.NewCmd())
-	root.AddCommand(build.NewCmd())
-	root.AddCommand(completion.NewCmd())
-	root.AddCommand(generate.NewCmd())
-	root.AddCommand(migrate.NewCmd())
-	root.AddCommand(new.NewCmd())
-	root.AddCommand(olmcatalog.NewCmd())
-	root.AddCommand(printdeps.NewCmd())
-	root.AddCommand(run.NewCmd())
-	root.AddCommand(scorecard.NewCmd())
-	root.AddCommand(test.NewCmd())
-	root.AddCommand(up.NewCmd())
-	root.AddCommand(version.NewCmd())
+	root := cli.GetCLIRoot()
 
 	root.PersistentFlags().Bool(flags.VerboseOpt, false, "Enable verbose logging")
 	if err := viper.BindPFlags(root.PersistentFlags()); err != nil {
@@ -85,49 +40,3 @@ func main() {
 		os.Exit(1)
 	}
 }
-
-func checkGoModulesForCmd(cmd *cobra.Command) (err error) {
-	// Certain commands are able to be run anywhere or handle this check
-	// differently in their CLI code.
-	if skipCheckForCmd(cmd) {
-		return nil
-	}
-	// Do not perform this check if the project is non-Go, as they will not
-	// be using go modules.
-	if !projutil.IsOperatorGo() {
-		return nil
-	}
-	// Do not perform a go modules check if the working directory is not in
-	// the project root, as some sub-commands might not require project root.
-	// Individual subcommands will perform this check as needed.
-	if err := projutil.CheckProjectRoot(); err != nil {
-		return nil
-	}
-
-	return projutil.CheckGoModules()
-}
-
-var commandsToSkip = map[string]struct{}{
-	"new":          struct{}{}, // Handles this logic in cmd/operator-sdk/new
-	"migrate":      struct{}{}, // Handles this logic in cmd/operator-sdk/migrate
-	"operator-sdk": struct{}{}, // Alias for "help"
-	"help":         struct{}{},
-	"completion":   struct{}{},
-	"version":      struct{}{},
-	"print-deps":   struct{}{}, // Does not require this logic
-}
-
-func skipCheckForCmd(cmd *cobra.Command) (skip bool) {
-	if _, ok := commandsToSkip[cmd.Name()]; ok {
-		return true
-	}
-	cmd.VisitParents(func(pc *cobra.Command) {
-		if _, ok := commandsToSkip[pc.Name()]; ok {
-			// The bare "operator-sdk" command will be checked above.
-			if pc.Name() != "operator-sdk" {
-				skip = true
-			}
-		}
-	})
-	return skip
-}

cmd/operator-sdk/new/cmd.go

@@ -45,6 +45,7 @@ generates a default directory layout based on the input <project-name>.
 <project-name> is the project name of the new operator. (e.g app-operator)
 
 For example:
+
 	$ mkdir $HOME/projects/example.com/
 	$ cd $HOME/projects/example.com/
 	$ operator-sdk new app-operator

doc/cli/operator-sdk.md

@@ -0,0 +1,32 @@
+## operator-sdk
+
+An SDK for building operators with ease
+
+### Synopsis
+
+An SDK for building operators with ease
+
+### Options
+
+```
+  -h, --help   help for operator-sdk
+```
+
+### SEE ALSO
+
+* [operator-sdk add](operator-sdk_add.md)	 - Adds a controller or resource to the project
+* [operator-sdk alpha](operator-sdk_alpha.md)	 - Run an alpha subcommand
+* [operator-sdk build](operator-sdk_build.md)	 - Compiles code and builds artifacts
+* [operator-sdk completion](operator-sdk_completion.md)	 - Generators for shell completions
+* [operator-sdk generate](operator-sdk_generate.md)	 - Invokes specific generator
+* [operator-sdk migrate](operator-sdk_migrate.md)	 - Adds source code to an operator
+* [operator-sdk new](operator-sdk_new.md)	 - Creates a new operator application
+* [operator-sdk olm-catalog](operator-sdk_olm-catalog.md)	 - Invokes a olm-catalog command
+* [operator-sdk print-deps](operator-sdk_print-deps.md)	 - Print Golang packages and versions required to run the operator
+* [operator-sdk run](operator-sdk_run.md)	 - Runs a generic operator
+* [operator-sdk scorecard](operator-sdk_scorecard.md)	 - Run scorecard tests
+* [operator-sdk test](operator-sdk_test.md)	 - Tests the operator
+* [operator-sdk up](operator-sdk_up.md)	 - Launches the operator
+* [operator-sdk version](operator-sdk_version.md)	 - Prints the version of operator-sdk
+
+###### Auto generated by spf13/cobra on 6-Nov-2019

doc/cli/operator-sdk_add.md

@@ -0,0 +1,22 @@
+## operator-sdk add
+
+Adds a controller or resource to the project
+
+### Synopsis
+
+Adds a controller or resource to the project
+
+### Options
+
+```
+  -h, --help   help for add
+```
+
+### SEE ALSO
+
+* [operator-sdk](operator-sdk.md)	 - An SDK for building operators with ease
+* [operator-sdk add api](operator-sdk_add_api.md)	 - Adds a new api definition under pkg/apis
+* [operator-sdk add controller](operator-sdk_add_controller.md)	 - Adds a new controller pkg
+* [operator-sdk add crd](operator-sdk_add_crd.md)	 - Adds a Custom Resource Definition (CRD) and the Custom Resource (CR) files
+
+###### Auto generated by spf13/cobra on 6-Nov-2019