Merge pull request #3224 from jmcshane/cli-docs

📖 Create CLI docs for workspace and create workspace cli

cli/cmd/kubectl-create-workspace/cmd/kubectlCreateWorkspace.go

@@ -0,0 +1,45 @@
+/*
+Copyright 2024 The KCP 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 cmd
+
+import (
+	goflags "flag"
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+
+	"k8s.io/cli-runtime/pkg/genericclioptions"
+	"k8s.io/klog/v2"
+
+	workspaceCmd "github.com/kcp-dev/kcp/cli/pkg/workspace/cmd"
+)
+
+func KubectlCreateWorkspaceCommand() *cobra.Command {
+	createWorkspaceCommand, err := workspaceCmd.NewCreate("kubectl create workspace", "", genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	// setup klog
+	fs := goflags.NewFlagSet("klog", goflags.PanicOnError)
+	klog.InitFlags(fs)
+	createWorkspaceCommand.PersistentFlags().AddGoFlagSet(fs)
+	return createWorkspaceCommand
+
+}

cli/cmd/kubectl-create-workspace/main.go

@@ -17,32 +17,18 @@ limitations under the License.
 package main
 
 import (
-	goflags "flag"
-	"fmt"
 	"os"
 
 	"github.com/spf13/pflag"
 
-	"k8s.io/cli-runtime/pkg/genericclioptions"
-	"k8s.io/klog/v2"
-
-	"github.com/kcp-dev/kcp/cli/pkg/workspace/cmd"
+	"github.com/kcp-dev/kcp/cli/cmd/kubectl-create-workspace/cmd"
 )
 
 func main() {
 	flags := pflag.NewFlagSet("kubectl-create-workspace", pflag.ExitOnError)
 	pflag.CommandLine = flags
 
-	createWorkspaceCmd, err := cmd.NewCreate("kubectl create workspace", "", genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr})
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "error: %v\n", err)
-		os.Exit(1)
-	}
-
-	// setup klog
-	fs := goflags.NewFlagSet("klog", goflags.PanicOnError)
-	klog.InitFlags(fs)
-	createWorkspaceCmd.PersistentFlags().AddGoFlagSet(fs)
+	createWorkspaceCmd := cmd.KubectlCreateWorkspaceCommand()
 
 	if err := createWorkspaceCmd.Execute(); err != nil {
 		os.Exit(1)

cli/cmd/kubectl-ws/cmd/kubectlWs.go

@@ -0,0 +1,45 @@
+/*
+Copyright 2024 The KCP 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 cmd
+
+import (
+	goflags "flag"
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+
+	"k8s.io/cli-runtime/pkg/genericclioptions"
+	"k8s.io/klog/v2"
+
+	workspaceCmd "github.com/kcp-dev/kcp/cli/pkg/workspace/cmd"
+)
+
+func KubectlWsCommand() *cobra.Command {
+	wsCommand, err := workspaceCmd.New(genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	// setup klog
+	fs := goflags.NewFlagSet("klog", goflags.PanicOnError)
+	klog.InitFlags(fs)
+	wsCommand.PersistentFlags().AddGoFlagSet(fs)
+	return wsCommand
+
+}

cli/cmd/kubectl-ws/main.go

@@ -17,32 +17,18 @@ limitations under the License.
 package main
 
 import (
-	goflags "flag"
-	"fmt"
 	"os"
 
 	"github.com/spf13/pflag"
 
-	"k8s.io/cli-runtime/pkg/genericclioptions"
-	"k8s.io/klog/v2"
-
-	"github.com/kcp-dev/kcp/cli/pkg/workspace/cmd"
+	"github.com/kcp-dev/kcp/cli/cmd/kubectl-ws/cmd"
 )
 
 func main() {
 	flags := pflag.NewFlagSet("kubectl-ws", pflag.ExitOnError)
 	pflag.CommandLine = flags
 
-	workspaceCmd, err := cmd.New(genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr})
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "error: %v\n", err)
-		os.Exit(1)
-	}
-
-	// setup klog
-	fs := goflags.NewFlagSet("klog", goflags.PanicOnError)
-	klog.InitFlags(fs)
-	workspaceCmd.PersistentFlags().AddGoFlagSet(fs)
+	workspaceCmd := cmd.KubectlWsCommand()
 
 	if err := workspaceCmd.Execute(); err != nil {
 		os.Exit(1)

docs/generators/cli-doc/main.go

@@ -22,7 +22,11 @@ import (
 	"log"
 	"os"
 
+	"github.com/spf13/cobra"
+
+	kubectlCreateWorkspace "github.com/kcp-dev/kcp/cli/cmd/kubectl-create-workspace/cmd"
 	kubectlKcp "github.com/kcp-dev/kcp/cli/cmd/kubectl-kcp/cmd"
+	kubectlWs "github.com/kcp-dev/kcp/cli/cmd/kubectl-ws/cmd"
 	"github.com/kcp-dev/kcp/hack/third_party/github.com/spf13/cobra/doc"
 )
 
@@ -40,6 +44,21 @@ func main() {
 	}
 
 	if err := doc.GenMarkdownTree(kubectlKcp.KubectlKcpCommand(), *output); err != nil {
-		log.Fatalf("Failed to generate docs: %v", err)
+		log.Fatalf("Failed to generate docs for kubectl-kcp: %v", err)
+	}
+
+	createWs := kubectlCreateWorkspace.KubectlCreateWorkspaceCommand()
+
+	// Override buildtime setup for clarity on the generated docs
+	// makes title `create_workspace` in line with other multi-part commands
+	createWs.Use = "workspace"
+	createParent := &cobra.Command{Use: "create"}
+	createParent.AddCommand(createWs)
+
+	if err := doc.GenMarkdownTree(createWs, *output); err != nil {
+		log.Fatalf("Failed to generate docs for kubectl-create-workspace: %v", err)
+	}
+	if err := doc.GenMarkdownTree(kubectlWs.KubectlWsCommand(), *output); err != nil {
+		log.Fatalf("Failed to generate docs for kubectl-ws: %v", err)
 	}
 }