docs: Update documentation for alpha commands (#3074)

kptdev · May 6, 2022 · 2be56a7 · 2be56a7
1 parent 6966150
commit 2be56a7
Show file tree

Hide file tree

Showing 45 changed files with 1,723 additions and 325 deletions.
diff --git a/commands/repocmd.go b/commands/repocmd.go
@@ -22,6 +22,7 @@ import (
 	"github.com/GoogleContainerTools/kpt/internal/cmdrepoget"
 	"github.com/GoogleContainerTools/kpt/internal/cmdreporeg"
 	"github.com/GoogleContainerTools/kpt/internal/cmdrepounreg"
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/repodocs"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	"github.com/spf13/cobra"
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -32,8 +33,8 @@ func NewRepoCommand(ctx context.Context, version string) *cobra.Command {
 	repo := &cobra.Command{
 		Use:     "repo",
 		Aliases: []string{"repository"},
-		Short:   "[Alpha] Manage package repositories.",
-		Long:    "[Alpha] The `repo` command group contains subcommands for managing package repositories.",
+		Short:   "[Alpha] " + repodocs.RepoShort,
+		Long:    "[Alpha] " + repodocs.RepoLong,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			h, err := cmd.Flags().GetBool("help")
 			if err != nil {

diff --git a/commands/rpkgcmd.go b/commands/rpkgcmd.go
@@ -29,6 +29,7 @@ import (
 	"github.com/GoogleContainerTools/kpt/internal/cmdrpkgpull"
 	"github.com/GoogleContainerTools/kpt/internal/cmdrpkgpush"
 	"github.com/GoogleContainerTools/kpt/internal/cmdrpkgreject"
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/rpkgdocs"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	"github.com/spf13/cobra"
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -39,8 +40,8 @@ func NewRpkgCommand(ctx context.Context, version string) *cobra.Command {
 	repo := &cobra.Command{
 		Use:     "rpkg",
 		Aliases: []string{"rpackage"},
-		Short:   "[Alpha] Manage packages in package repositories.",
-		Long:    "[Alpha] The `rpkg` command group contains subcommands for managing packages in repositories.",
+		Short:   "[Alpha] " + rpkgdocs.RpkgShort,
+		Long:    "[Alpha] " + rpkgdocs.RpkgLong,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			h, err := cmd.Flags().GetBool("help")
 			if err != nil {

diff --git a/commands/synccmd.go b/commands/synccmd.go
@@ -22,6 +22,7 @@ import (
 	"github.com/GoogleContainerTools/kpt/internal/cmdsync/create"
 	"github.com/GoogleContainerTools/kpt/internal/cmdsync/delete"
 	"github.com/GoogleContainerTools/kpt/internal/cmdsync/get"
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/syncdocs"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	"github.com/spf13/cobra"
 	"k8s.io/cli-runtime/pkg/genericclioptions"
@@ -31,8 +32,8 @@ import (
 func NewSyncCommand(ctx context.Context, version string) *cobra.Command {
 	sync := &cobra.Command{
 		Use:   "sync",
-		Short: "[Alpha] Sync packages with deployment clusters.",
-		Long:  "[Alpha] The `sync` command group contains subcommands for managing syncing of packages with deployment clusters using Config Sync.",
+		Short: "[Alpha] " + syncdocs.SyncShort,
+		Long:  "[Alpha] " + syncdocs.SyncLong,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			h, err := cmd.Flags().GetBool("help")
 			if err != nil {

diff --git a/internal/cmdrepoget/command.go b/internal/cmdrepoget/command.go
@@ -18,6 +18,7 @@ import (
 	"context"
 	"strings"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/repodocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	"github.com/spf13/cobra"
@@ -30,11 +31,6 @@ import (
 
 const (
 	command = "cmdrepoget"
-	longMsg = `
-kpt alpha repo get [flags]
-
-Lists repositories registered with Package Orchestrator.
-`
 )
 
 func NewCommand(ctx context.Context, rcg *genericclioptions.ConfigFlags) *cobra.Command {
@@ -48,11 +44,11 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 		printFlags: get.NewGetPrintFlags(),
 	}
 	c := &cobra.Command{
-		Use:     "get [REPOSITORY]",
+		Use:     "get [REPOSITORY_NAME]",
 		Aliases: []string{"ls", "list"},
-		Short:   "Lists repositories registered with Package Orchestrator.",
-		Long:    longMsg,
-		Example: "kpt alpha repo list --namespace default",
+		Short:   repodocs.GetShort,
+		Long:    repodocs.GetShort + "\n" + repodocs.GetLong,
+		Example: repodocs.GetExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdreporeg/command.go b/internal/cmdreporeg/command.go
@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/repodocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	configapi "github.com/GoogleContainerTools/kpt/porch/api/porchconfig/v1alpha1"
@@ -31,38 +32,6 @@ import (
 
 const (
 	command = "cmdreporeg"
-	longMsg = `
-kpt alpha repo reg[ister] REPOSITORY [flags]
-
-Args:
-
-REPOSITORY:
-  Address of the repository to register. Required argument.
-
-Flags:
-
---description
-  Brief description of the package repository.
-
---name
-  Name of the package repository. If unspecified, will use the name portion (last segment) of the repository URL.
-
---deployment
-  Repository is a deployment repository; packages in a deployment repository are considered deployment-ready.
-
---repo-basic-username
-  Username for repository authentication with basic auth.
-
---repo-basic-password
-  Password for repository authentication with basic auth.
-
---directory
-  Directory within the repository where to look for packages.
-
---branch
-  Branch in the repository where finalized packages are committed.
-
-`
 )
 
 func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner {
@@ -73,9 +42,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 	c := &cobra.Command{
 		Use:     "reg REPOSITORY",
 		Aliases: []string{"register"},
-		Short:   "Registers a package repository with Package Orchestrator.",
-		Long:    longMsg,
-		Example: "kpt alpha repo register https://github.com/platkrm/demo-blueprints.git --namespace=default",
+		Short:   repodocs.RegShort,
+		Long:    repodocs.RegShort + "\n" + repodocs.RegLong,
+		Example: repodocs.RegExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdrepounreg/command.go b/internal/cmdrepounreg/command.go
@@ -18,6 +18,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/repodocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	configapi "github.com/GoogleContainerTools/kpt/porch/api/porchconfig/v1alpha1"
@@ -30,21 +31,6 @@ import (
 
 const (
 	command = "cmdrepounreg"
-	longMsg = `
-kpt alpha repo unreg REPOSITORY [flags]
-
-Unregisters a package repository from Package Orchestrator.
-
-Args:
-
-REPOSITORY:
-  Name of the registered repoisitory resource to unregister.
-
-Flags:
-
---keep-auth-secret
-  Do not delete the repository authentication secret, if it exists.
-`
 )
 
 func NewCommand(ctx context.Context, rcg *genericclioptions.ConfigFlags) *cobra.Command {
@@ -59,9 +45,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 	c := &cobra.Command{
 		Use:     "unreg REPOSITORY [flags]",
 		Aliases: []string{"unregister"},
-		Short:   "Unregisters a package repository from Package Orchestrator.",
-		Long:    longMsg,
-		Example: "kpt alpha repo unregister registered-repository --keep-auth-secret",
+		Short:   repodocs.UnregShort,
+		Long:    repodocs.UnregShort + "\n" + repodocs.UnregLong,
+		Example: repodocs.UnregExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdrpkgapprove/command.go b/internal/cmdrpkgapprove/command.go
@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/rpkgdocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	"github.com/GoogleContainerTools/kpt/porch/api/porch/v1alpha1"
@@ -30,16 +31,6 @@ import (
 
 const (
 	command = "cmdrpkgapprove"
-	longMsg = `
-kpt alpha rpkg approve [PACKAGE ...] [flags]
-
-Approves a proposal to finalize a package revision
-
-Args:
-
-PACKAGE:
-  Name of the proposed package revisions to approve.
-`
 )
 
 func NewCommand(ctx context.Context, rcg *genericclioptions.ConfigFlags) *cobra.Command {
@@ -55,9 +46,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 
 	c := &cobra.Command{
 		Use:     "approve PACKAGE",
-		Short:   "Approves a proposal to finalize a package revision.",
-		Long:    longMsg,
-		Example: "kpt alpha rpkg approve package-name",
+		Short:   rpkgdocs.ApproveShort,
+		Long:    rpkgdocs.ApproveShort + "\n" + rpkgdocs.ApproveLong,
+		Example: rpkgdocs.ApproveExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdrpkgclone/command.go b/internal/cmdrpkgclone/command.go
@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/rpkgdocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/parse"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
@@ -31,45 +32,6 @@ import (
 
 const (
 	command = "cmdrpkgclone"
-	longMsg = `
-kpt alpha rpkg clone SOURCE_PACKAGE TARGET
-
-Creates a clone of a source package in the target repository.
-
-Args:
-
-SOURCE_PACKAGE:
-  Source package. Can be a reference to an OCI package, Git package, or an package resource name:
-    * oci://oci-repository/package-name
-    * http://git-repository.git/package-name
-    * package-revision-name
-
-  With git URLs, you can either include the package directory and ref in SOURCE_PACKAGE, or
-  you can individually specify the repo, ref, and directory using flags:
-    * kpt alpha rpkg clone http://git-repository.git/package-name@main target --repository=repo
-    * kpt alpha rpkg clone http://git-repository.git target --directory=package-name --ref=main --repository=repo
-
-NAME:
-  Target package revision name (downstream package)
-  Example: package-name
-
-Flags:
-
---directory
-  Directory within the repository where the upstream package is located.
-
---ref
-  Ref in the repository where the upstream package is located (branch, tag, SHA). The default is 'main'.
-
---repository
-  Repository to which package will be cloned (downstream repository).
-
---revision
-  Revision of the downstream package.
-
---strategy
-  Update strategy that should be used when updating this package; one of: resource-merge, fast-forward, force-delete-replace.
-`
 )
 
 var (
@@ -91,9 +53,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 	}
 	c := &cobra.Command{
 		Use:     "clone SOURCE_PACKAGE NAME",
-		Short:   "Creates a clone of a source package in the target repository.",
-		Long:    longMsg,
-		Example: "kpt alpha rpkg clone upstream-package-name target-package-name --repository target-repository --revision v1",
+		Short:   rpkgdocs.CloneShort,
+		Long:    rpkgdocs.CloneShort + "\n" + rpkgdocs.CloneLong,
+		Example: rpkgdocs.CloneExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdrpkgcopy/command.go b/internal/cmdrpkgcopy/command.go
@@ -18,6 +18,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/rpkgdocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	porchapi "github.com/GoogleContainerTools/kpt/porch/api/porch/v1alpha1"
@@ -29,28 +30,6 @@ import (
 
 const (
 	command = "cmdrpkgcopy"
-	longMsg = `
-kpt alpha rpkg copy SOURCE_PACKAGE NAME
-
-Creates a new copy of a source package in the target repository.
-
-Args:
-
-SOURCE_PACKAGE:
-  Source package. Must be a package resource name: <repository>-<hash>
-
-NAME:
-  Target package revision name
-  Example: package-name
-
-Flags:
-
---repository
-  Repository to which package will be copied.
-
---revision
-  Revision of the downstream package.
-`
 )
 
 func NewCommand(ctx context.Context, rcg *genericclioptions.ConfigFlags) *cobra.Command {
@@ -65,9 +44,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 	c := &cobra.Command{
 		Use:     "copy SOURCE_PACKAGE NAME",
 		Aliases: []string{"edit"},
-		Short:   "Creates a copy of a source package in the target repository.",
-		Long:    longMsg,
-		Example: "kpt alpha rpkg copy upstream-package-name target-package-name --repository target-repository --revision v1",
+		Short:   rpkgdocs.CopyShort,
+		Long:    rpkgdocs.CopyShort + "\n" + rpkgdocs.CopyLong,
+		Example: rpkgdocs.CopyExamples,
 		PreRunE: r.preRunE,
 		RunE:    r.runE,
 		Hidden:  porch.HidePorchCommands,

diff --git a/internal/cmdrpkgdel/command.go b/internal/cmdrpkgdel/command.go
@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/GoogleContainerTools/kpt/internal/docs/generated/rpkgdocs"
 	"github.com/GoogleContainerTools/kpt/internal/errors"
 	"github.com/GoogleContainerTools/kpt/internal/util/porch"
 	porchapi "github.com/GoogleContainerTools/kpt/porch/api/porch/v1alpha1"
@@ -31,14 +32,6 @@ import (
 
 const (
 	command = "cmdrpkgdel"
-	longMsg = `
-kpt alpha rpkg del[ete] [PACKAGE ...] [flags]
-
-Args:
-
-PACKAGE:
-  One or more ames of the package revisions to delete.
-`
 )
 
 func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner {
@@ -50,9 +43,9 @@ func newRunner(ctx context.Context, rcg *genericclioptions.ConfigFlags) *runner
 		Use:        "del PACKAGE",
 		Aliases:    []string{"delete"},
 		SuggestFor: []string{},
-		Short:      "Deletes one or more packages in registered repositories.",
-		Long:       longMsg,
-		Example:    "kpt alpha rpkg del repository:package:v1 --namespace=default",
+		Short:      rpkgdocs.DelShort,
+		Long:       rpkgdocs.DelShort + "\n" + rpkgdocs.DelLong,
+		Example:    rpkgdocs.DelExamples,
 		PreRunE:    r.preRunE,
 		RunE:       r.runE,
 		Hidden:     porch.HidePorchCommands,