cli: add minimal doc generator (#129)

* cli: add minimal doc generator

* fixup! cli: add

cli/cmd/root.go

@@ -9,20 +9,39 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var rootCmd = &cobra.Command{
-	Use:              "constellation",
-	Short:            "Manage your Constellation cluster",
-	Long:             "Manage your Constellation cluster.",
-	PersistentPreRun: preRunRoot,
-}
-
 // Execute starts the CLI.
 func Execute() error {
+	rootCmd := NewRootCmd()
 	ctx, cancel := signalContext(context.Background(), os.Interrupt)
 	defer cancel()
 	return rootCmd.ExecuteContext(ctx)
 }
 
+// NewRootCmd creates the root command.
+func NewRootCmd() *cobra.Command {
+	rootCmd := &cobra.Command{
+		Use:              "constellation",
+		Short:            "Manage your Constellation cluster",
+		Long:             "Manage your Constellation cluster.",
+		PersistentPreRun: preRunRoot,
+	}
+
+	// Set output of cmd.Print to stdout. (By default, it's stderr.)
+	rootCmd.SetOut(os.Stdout)
+
+	rootCmd.PersistentFlags().String("dev-config", "", "use settings from a development config")
+	must(rootCmd.MarkPersistentFlagFilename("dev-config", "json"))
+
+	rootCmd.AddCommand(newCreateCmd())
+	rootCmd.AddCommand(newInitCmd())
+	rootCmd.AddCommand(newVerifyCmd())
+	rootCmd.AddCommand(newRecoverCmd())
+	rootCmd.AddCommand(newTerminateCmd())
+	rootCmd.AddCommand(newVersionCmd())
+
+	return rootCmd
+}
+
 // signalContext returns a context that is canceled on the handed signal.
 // The signal isn't watched after its first occurrence. Call the cancel
 // function to ensure the internal goroutine is stopped and the signal isn't
@@ -50,20 +69,6 @@ func signalContext(ctx context.Context, sig os.Signal) (context.Context, context
 	return sigCtx, cancelFunc
 }
 
-func init() {
-	cobra.EnableCommandSorting = false
-	// Set output of cmd.Print to stdout. (By default, it's stderr.)
-	rootCmd.SetOut(os.Stdout)
-	rootCmd.PersistentFlags().String("dev-config", "", "use settings from a development config")
-	must(rootCmd.MarkPersistentFlagFilename("dev-config", "json"))
-	rootCmd.AddCommand(newCreateCmd())
-	rootCmd.AddCommand(newInitCmd())
-	rootCmd.AddCommand(newVerifyCmd())
-	rootCmd.AddCommand(newRecoverCmd())
-	rootCmd.AddCommand(newTerminateCmd())
-	rootCmd.AddCommand(newVersionCmd())
-}
-
 func preRunRoot(cmd *cobra.Command, args []string) {
 	cmd.SilenceUsage = true
 }

cli/main.go

@@ -4,9 +4,11 @@ import (
 	"os"
 
 	"github.com/edgelesssys/constellation/cli/cmd"
+	"github.com/spf13/cobra"
 )
 
 func main() {
+	cobra.EnableCommandSorting = false
 	if err := cmd.Execute(); err != nil {
 		os.Exit(1)
 	}

go.mod

@@ -104,9 +104,11 @@ require (
 )
 
 require (
+	github.com/cpuguy83/go-md2man/v2 v2.0.1 // indirect
 	github.com/fsnotify/fsnotify v1.5.1 // indirect
 	github.com/onsi/ginkgo v1.16.5 // indirect
 	github.com/onsi/gomega v1.17.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 )
 
 require (

go.sum

@@ -501,6 +501,7 @@ github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfc
 github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.1 h1:r/myEWzV9lfsM1tFLgDyu0atFtJ1fXn261LKYj/3DxU=
 github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -1304,6 +1305,7 @@ github.com/rs/cors v1.8.0/go.mod h1:EBwu+T5AvHOcXwvZIkQFjUN6s8Czyqw12GL/Y0tUyRM=
 github.com/rubiojr/go-vhd v0.0.0-20200706105327-02e210299021/go.mod h1:DM5xW0nvfNNm2uytzsvhI3OnX8uzaRAg8UX/CnDqbto=
 github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/ryanuber/columnize v2.1.0+incompatible/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=

util/clidocgen/main.go

@@ -0,0 +1,32 @@
+// Clidocgen generates a Markdown page describing all CLI commands.
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+
+	"github.com/edgelesssys/constellation/cli/cmd"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	rootCmd := cmd.NewRootCmd()
+	rootCmd.DisableAutoGenTag = true
+
+	// Generate Markdown for all commands.
+	cmdList := &bytes.Buffer{}
+	body := &bytes.Buffer{}
+	for _, c := range rootCmd.Commands() {
+		name := c.Name()
+		fmt.Fprintf(cmdList, "* [%v](#constellation-%v): %v\n", name, name, c.Short)
+		if err := doc.GenMarkdown(c, body); err != nil {
+			panic(err)
+		}
+	}
+
+	// Remove "see also" sections. They list parent and child commands, which is not interesting for us.
+	cleanedBody := regexp.MustCompile(`(?s)### SEE ALSO\n.+?\n\n`).ReplaceAll(body.Bytes(), nil)
+
+	fmt.Printf("Commands:\n\n%s\n%s", cmdList, cleanedBody)
+}