Separate hidden and non-hidden commands in lakectl docs

Also add a scary banner so people know not to use them.

cmd/lakectl/cmd/docs.go

@@ -84,6 +84,23 @@ the Docker container. That is to say, ` + "`localhost`" + ` to a Docker containe
 ## Command Reference
 `
 
+var cliReferenceHiddenCommandsSeparator = `
+-------
+
+## Undocumented commands
+
+**note:** These commands are plumbing commands and for internal use only.
+Avoid using them unless you're _really_ sure you know what you're doing, or
+have been in contact with lakeFS support!{: .note .note-warning }
+
+`
+
+var cliReferenceHiddenCommandBanner = `**note:**
+lakeFS plumbing command. Don't use unless you're _really_ sure you know what you're doing.
+{: .note .note-warning }
+
+`
+
 func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(buf)
@@ -103,9 +120,11 @@ func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
 	return nil
 }
 
-// this is a version of github.com/spf13/cobra/doc that fits better
-// into lakeFS' docs.
-func genMarkdownForCmd(cmd *cobra.Command, w io.Writer) error {
+// genMarkdownForCmd is a version of github.com/spf13/cobra/doc that fits
+// better into lakeFS' docs.  It generates documentation for cmd, then for
+// its subcommands.  topLevel adds a scarier header before those hidden
+// subcommands.
+func genMarkdownForCmd(cmd *cobra.Command, w io.Writer, topLevel bool) error {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
 
@@ -115,7 +134,7 @@ func genMarkdownForCmd(cmd *cobra.Command, w io.Writer) error {
 	buf.WriteString("### " + name + "\n\n")
 
 	if cmd.Hidden {
-		buf.WriteString("**note:** This command is a lakeFS plumbing command. Don't use it unless you're really sure you know what you're doing.\n{: .note .note-warning }\n\n")
+		buf.WriteString(cliReferenceHiddenCommandBanner)
 	}
 
 	buf.WriteString(cmd.Short + "\n\n")
@@ -144,11 +163,37 @@ func genMarkdownForCmd(cmd *cobra.Command, w io.Writer) error {
 	}
 
 	// recurse to children
+	hasHidden := false
 	for _, c := range cmd.Commands() {
-		err := genMarkdownForCmd(c, w)
+		if c.Hidden {
+			hasHidden = true
+			continue
+		}
+		err := genMarkdownForCmd(c, w, false)
+		if err != nil {
+			return err
+		}
+	}
+
+	if hasHidden {
+		sep := "\n---------\n"
+		if topLevel {
+			sep = cliReferenceHiddenCommandsSeparator
+		}
+		_, err := io.WriteString(w, sep)
 		if err != nil {
 			return err
 		}
+
+		for _, c := range cmd.Commands() {
+			if !c.Hidden {
+				continue
+			}
+			err := genMarkdownForCmd(c, w, false)
+			if err != nil {
+				return err
+			}
+		}
 	}
 
 	return nil
@@ -176,7 +221,7 @@ var docsCmd = &cobra.Command{
 		if err != nil {
 			DieErr(err)
 		}
-		err = genMarkdownForCmd(rootCmd, writer)
+		err = genMarkdownForCmd(rootCmd, writer, true)
 		if err != nil {
 			DieErr(err)
 		}