Add website for pulsarctl (#77)

* Add website for pulsarctl

Signed-off-by: xiaolong.ran <ranxiaolong716@gmail.com>

.github/workflows/go.yml

@@ -32,6 +32,7 @@ jobs:
         docker run -d -p 8080:8080 -p 6650:6650 -v ${PWD}:/pulsar_test -v ${PWD}/data:/pulsar/data --name pulsarctl apachepulsar/pulsar:latest bin/pulsar standalone
         docker cp pulsar-io-kafka-2.4.0.nar pulsarctl:/pulsar
         docker cp pulsar-io-jdbc-2.4.0.nar pulsarctl:/pulsar
+        docker cp pulsarctl:/pulsar/pulsar-io-kafka-2.4.0.nar ${PWD}/test/sources/
         docker cp pulsarctl:/pulsar/pulsar-io-jdbc-2.4.0.nar ${PWD}/test/sinks/
         docker cp ${PWD}/test/sources/kafkaSourceConfig.yaml pulsarctl:/pulsar/conf
         docker cp ${PWD}/test/sinks/mysql-jdbc-sink.yaml pulsarctl:/pulsar/conf

.gitignore

@@ -12,6 +12,12 @@ kafka-clients-0.10.2.1.jar
 pulsar-io-jdbc-2.4.0.nar
 data
 
+# Website
+
+site/gen-pulsarctldocs/generators/includes
+site/gen-pulsarctldocs/generators/build/*
+!site/gen-pulsarctldocs/generators/build/index.html
+
 # Test binary, build with `go test -c`
 *.test
 

Makefile

@@ -0,0 +1,13 @@
+MINOR_VERSION=1
+
+# Build pulsarctl docs
+
+cleancli:
+	sudo rm -f main
+	sudo rm -rf $(shell pwd)/site/gen-pulsarctldocs/generators/includes
+	sudo rm -rf $(shell pwd)/site/gen-pulsarctldocs/generators/build
+	sudo rm -rf $(shell pwd)/site/gen-pulsarctldocs/generators/manifest.json
+
+cli: cleancli
+	go run site/gen-pulsarctldocs/main.go --pulsar-version v1_$(MINOR_VERSION)
+	docker run -v ${PWD}/site/gen-pulsarctldocs/generators/includes:/source -v ${PWD}/site/gen-pulsarctldocs/generators/build:/build -v ${PWD}/site/gen-pulsarctldocs/generators/:/manifest pwittrock/brodocs

main.go

@@ -21,83 +21,12 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/streamnative/pulsarctl/pkg/cmdutils"
-	"github.com/streamnative/pulsarctl/pkg/ctl/cluster"
-	"github.com/streamnative/pulsarctl/pkg/ctl/completion"
-	"github.com/streamnative/pulsarctl/pkg/ctl/functions"
-	"github.com/streamnative/pulsarctl/pkg/ctl/namespace"
-	"github.com/streamnative/pulsarctl/pkg/ctl/schemas"
-	"github.com/streamnative/pulsarctl/pkg/ctl/sinks"
-	"github.com/streamnative/pulsarctl/pkg/ctl/sources"
-	"github.com/streamnative/pulsarctl/pkg/ctl/tenant"
-	"github.com/streamnative/pulsarctl/pkg/ctl/topic"
-
-	"github.com/kris-nova/logger"
-	"github.com/spf13/cobra"
+	"github.com/streamnative/pulsarctl/pkg"
 )
 
-var rootCmd = &cobra.Command{
-	Use:   "pulsarctl [command]",
-	Short: "a CLI for Apache Pulsar",
-	Run: func(cmd *cobra.Command, _ []string) {
-		if err := cmd.Help(); err != nil {
-			logger.Debug("ignoring error %q", err.Error())
-		}
-	},
-}
-
-func init() {
-
-	var colorValue string
-
-	flagGrouping := cmdutils.NewGrouping()
-
-	addCommands(flagGrouping)
-
-	rootCmd.PersistentFlags().BoolP("help", "h", false, "help for this command")
-	rootCmd.PersistentFlags().StringVarP(&colorValue, "color", "C", "true", "toggle colorized logs (true,false,fabulous)")
-	rootCmd.PersistentFlags().IntVarP(&logger.Level, "verbose", "v", 3, "set log level, use 0 to silence, 4 for debugging")
-	// add the common pulsarctl flags
-	rootCmd.PersistentFlags().AddFlagSet(cmdutils.PulsarCtlConfig.FlagSet())
-
-	cobra.OnInitialize(func() {
-		// Control colored output
-		color := true
-		fabulous := false
-		switch colorValue {
-		case "false":
-			color = false
-		case "fabulous":
-			color = false
-			fabulous = true
-		}
-		logger.Color = color
-		logger.Fabulous = fabulous
-
-		// Add timestamps for debugging
-		logger.Timestamps = false
-		if logger.Level >= 4 {
-			logger.Timestamps = true
-		}
-	})
-
-	rootCmd.SetUsageFunc(flagGrouping.Usage)
-}
-
-func addCommands(flagGrouping *cmdutils.FlagGrouping) {
-	rootCmd.AddCommand(cluster.Command(flagGrouping))
-	rootCmd.AddCommand(tenant.Command(flagGrouping))
-	rootCmd.AddCommand(completion.Command(rootCmd))
-	rootCmd.AddCommand(functions.Command(flagGrouping))
-	rootCmd.AddCommand(topic.Command(flagGrouping))
-	rootCmd.AddCommand(sources.Command(flagGrouping))
-	rootCmd.AddCommand(sinks.Command(flagGrouping))
-	rootCmd.AddCommand(topic.Command(flagGrouping))
-	rootCmd.AddCommand(namespace.Command(flagGrouping))
-	rootCmd.AddCommand(schemas.Command(flagGrouping))
-}
-
 func main() {
+	rootCmd := pkg.NewPulsarctlCmd()
+
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Println(err) // outputs cobra errors
 		os.Exit(-1)

pkg/cmdutils/group.go

@@ -96,6 +96,11 @@ func (g *FlagGrouping) Usage(cmd *cobra.Command) error {
 		}
 	}
 
+	if cmd.HasExample() {
+		usage = append(usage, "\nExamples:")
+		usage = append(usage, cmd.Example)
+	}
+
 	if len(cmd.Aliases) > 0 {
 		usage = append(usage, "\nAliases: "+cmd.NameAndAliases())
 	}

pkg/cmdutils/verb.go

@@ -53,11 +53,12 @@ func AddVerbCmds(flagGrouping *FlagGrouping, parentResourceCmd *cobra.Command, n
 }
 
 // SetDescription sets usage along with short and long descriptions as well as aliases
-func (vc *VerbCmd) SetDescription(use, short, long string, aliases ...string) {
+func (vc *VerbCmd) SetDescription(use, short, long, example string, aliases ...string) {
 	vc.Command.Use = use
 	vc.Command.Short = short
 	vc.Command.Long = long
 	vc.Command.Aliases = aliases
+	vc.Command.Example = example
 }
 
 // SetRunFunc registers a command function

pkg/ctl/cluster/cluster.go

@@ -32,7 +32,7 @@ var argsError = pulsar.Output{
 
 var clusterNonExist = pulsar.Output{
 	Desc: "the specified cluster does not exist in the broker",
-	Out:  "[✖]  code: 412 reason: Cluster <cluster-name> does not exist.",
+	Out:  "[✖]  code: 412 reason: Cluster (cluster-name) does not exist.",
 }
 
 var failureDomainArgsError = pulsar.Output{

pkg/ctl/cluster/create.go

@@ -25,16 +25,35 @@ import (
 )
 
 func CreateClusterCmd(vc *cmdutils.VerbCmd) {
+	var desc pulsar.LongDescription
+	desc.CommandUsedFor = "This command is used for adding the configuration data for a cluster. " +
+		"The configuration data is mainly used for geo-replication between clusters, so please " +
+		"make sure the service urls provided in this command are reachable between clusters. " +
+		"This operation requires Pulsar super-user privileges."
+	desc.CommandPermission = "This command requires super-user permissions."
+
+	var examples []pulsar.Example
+	create := pulsar.Example{
+		Desc:    "Provisions a new cluster",
+		Command: "pulsarctl clusters create (cluster-name)",
+	}
+	examples = append(examples, create)
+	desc.CommandExamples = examples
+
+	var out []pulsar.Output
+	successOut := pulsar.Output{
+		Desc: "normal output",
+		Out:  "Cluster (cluster-name) added",
+	}
+	out = append(out, successOut)
+	desc.CommandOutput = out
+
 	// update the description
 	vc.SetDescription(
 		"add",
 		"Add a pulsar cluster",
-		"This command is used for adding the configuration data for a cluster.\n"+
-			"The configuration data is mainly used for geo-replication between clusters,\n"+
-			"so please make sure the service urls provided in this command are reachable\n"+
-			"between clusters.\n"+
-			"\n"+
-			"This operation requires Pulsar super-user privileges.",
+		desc.ToString(),
+		desc.ExampleToString(),
 		"create")
 
 	clusterData := &pulsar.ClusterData{}

pkg/ctl/cluster/create_failure_domain.go

@@ -27,33 +27,33 @@ import (
 
 func createFailureDomainCmd(vc *cmdutils.VerbCmd) {
 	var desc pulsar.LongDescription
-	desc.CommandUsedFor = "This command is used for creating a failure domain of the <cluster-name>."
+	desc.CommandUsedFor = "This command is used for creating a failure domain of the (cluster-name)."
 	desc.CommandPermission = "This command requires super-user permissions."
 
 	var examples []pulsar.Example
 	create := pulsar.Example{
 		Desc:    "create the failure domain",
-		Command: "pulsarctl clusters create-failure-domain <cluster-name> <domain-name>",
+		Command: "pulsarctl clusters create-failure-domain (cluster-name) (domain-name)",
 	}
 	examples = append(examples, create)
 
 	createWithBrokers := pulsar.Example{
 		Desc: "create the failure domain with brokers",
 		Command: "pulsarctl clusters create-failure-domain" +
-			" -b <broker-ip>:<broker-port> -b <broker-ip>:<broker-port> <cluster-name> <domain-name>",
+			" -b (broker-ip):(broker-port) -b (broker-ip):(broker-port) (cluster-name) (domain-name)",
 	}
 	examples = append(examples, createWithBrokers)
 	desc.CommandExamples = examples
 
 	var out []pulsar.Output
 	successOut := pulsar.Output{
 		Desc: "normal output",
-		Out:  "Create failure domain <domain-name> for cluster <cluster-name> succeed",
+		Out:  "Create failure domain (domain-name) for cluster (cluster-name) succeed",
 	}
 	out = append(out, successOut)
 
 	argsErrorOut := pulsar.Output{
-		Desc: "the args need to be specified as <cluster-name> <domain-name>",
+		Desc: "the args need to be specified as (cluster-name) (domain-name)",
 		Out:  "[✖]  need specified two names for cluster and failure domain",
 	}
 	out = append(out, argsErrorOut)
@@ -64,6 +64,7 @@ func createFailureDomainCmd(vc *cmdutils.VerbCmd) {
 		"create-failure-domain",
 		"Create a failure domain",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"cfd")
 
 	var failureDomainData pulsar.FailureDomainData

pkg/ctl/cluster/delete.go

@@ -29,16 +29,16 @@ func deleteClusterCmd(vc *cmdutils.VerbCmd) {
 
 	var examples []pulsar.Example
 	delete := pulsar.Example{
-		Desc:    "deleting the cluster named <cluster-name>",
-		Command: "pulsarctl clusters delete <cluster-name>",
+		Desc:    "deleting the cluster named (cluster-name)",
+		Command: "pulsarctl clusters delete (cluster-name)",
 	}
 	examples = append(examples, delete)
 	desc.CommandExamples = examples
 
 	var out []pulsar.Output
 	successOut := pulsar.Output{
 		Desc: "normal output",
-		Out:  "Cluster <cluster-name> delete successfully.",
+		Out:  "Cluster (cluster-name) delete successfully.",
 	}
 	out = append(out, successOut)
 	out = append(out, argsError)
@@ -49,6 +49,7 @@ func deleteClusterCmd(vc *cmdutils.VerbCmd) {
 		"delete",
 		"Delete an existing cluster",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"delete")
 
 	vc.SetRunFuncWithNameArg(func() error {

pkg/ctl/cluster/delete_failure_domain.go

@@ -24,22 +24,22 @@ import (
 
 func deleteFailureDomainCmd(vc *cmdutils.VerbCmd) {
 	var desc pulsar.LongDescription
-	desc.CommandUsedFor = "This command is used for deleting the failure domain <domain-name>" +
-		" of the cluster <cluster-name>"
+	desc.CommandUsedFor = "This command is used for deleting the failure domain (domain-name) " +
+		"of the cluster (cluster-name)"
 	desc.CommandPermission = "This command requires super-user permissions."
 
 	var examples []pulsar.Example
 	delete := pulsar.Example{
 		Desc:    "delete the failure domain",
-		Command: "pulsarctl clusters delete-failure-domain <cluster-name> <domain-name>",
+		Command: "pulsarctl clusters delete-failure-domain (cluster-name) (domain-name)",
 	}
 	examples = append(examples, delete)
 	desc.CommandExamples = examples
 
 	var out []pulsar.Output
 	successOut := pulsar.Output{
 		Desc: "output example",
-		Out:  "Delete failure domain [<domain-name>] for cluster [<cluster-name>] succeed",
+		Out:  "Delete failure domain [(domain-name)] for cluster [(cluster-name)] succeed",
 	}
 	out = append(out, successOut, failureDomainArgsError)
 
@@ -62,6 +62,7 @@ func deleteFailureDomainCmd(vc *cmdutils.VerbCmd) {
 		"delete-failure-domain",
 		"Delete a failure domain",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"dfd")
 
 	vc.SetRunFuncWithMultiNameArgs(func() error {

pkg/ctl/cluster/get.go

@@ -33,8 +33,8 @@ func getClusterDataCmd(vc *cmdutils.VerbCmd) {
 
 	var examples []pulsar.Example
 	get := pulsar.Example{
-		Desc:    "getting the <cluster-name> data",
-		Command: "pulsarctl clusters get <cluster-name>",
+		Desc:    "getting the (cluster-name) data",
+		Command: "pulsarctl clusters get (cluster-name)",
 	}
 	examples = append(examples, get)
 
@@ -60,6 +60,7 @@ func getClusterDataCmd(vc *cmdutils.VerbCmd) {
 		"get",
 		"Get the configuration data for the specified cluster",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"get")
 
 	vc.SetRunFuncWithNameArg(func() error {

pkg/ctl/cluster/get_failure_domain.go

@@ -29,8 +29,8 @@ func getFailureDomainCmd(vc *cmdutils.VerbCmd) {
 
 	var examples []pulsar.Example
 	get := pulsar.Example{
-		Desc:    "getting the broker list in the <cluster-name> cluster failure domain <domain-name>",
-		Command: "pulsarctl clusters get-failure-domain <cluster-name> <domain-name>",
+		Desc:    "getting the broker list in the (cluster-name) cluster failure domain (domain-name)",
+		Command: "pulsarctl clusters get-failure-domain (cluster-name) (domain-name)",
 	}
 	examples = append(examples, get)
 
@@ -53,6 +53,7 @@ func getFailureDomainCmd(vc *cmdutils.VerbCmd) {
 		"get-failure-domain",
 		"Get the failure domain",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"gfd")
 
 	vc.SetRunFuncWithMultiNameArgs(func() error {

pkg/ctl/cluster/get_peer_clusters.go

@@ -31,8 +31,8 @@ func getPeerClustersCmd(vc *cmdutils.VerbCmd) {
 
 	var examples []pulsar.Example
 	get := pulsar.Example{
-		Desc:    "getting the <cluster-name> peer clusters",
-		Command: "pulsarctl clusters get-peer-clusters <cluster-name>",
+		Desc:    "getting the (cluster-name) peer clusters",
+		Command: "pulsarctl clusters get-peer-clusters (cluster-name)",
 	}
 	examples = append(examples, get)
 	desc.CommandExamples = examples
@@ -56,6 +56,7 @@ func getPeerClustersCmd(vc *cmdutils.VerbCmd) {
 		"get-peer-clusters",
 		"Getting list of peer clusters",
 		desc.ToString(),
+		desc.ExampleToString(),
 		"gpc")
 
 	vc.SetRunFuncWithNameArg(func() error {