enable changing the command separator when generating markdown

In certain cases, hyphens are preferred over underscores for command
separators.

doc/md_docs.go

@@ -26,6 +26,22 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// GenMarkdownOptions is the options for generating the man pages.
+// Used only in GenMarkdownWithOpts.
+type GenMarkdownOptions struct {
+	Writer           io.Writer
+	LinkHandler      func(string) string
+	CommandSeparator string
+}
+
+// GenMarkdownTreeOptions is the options for generating the man pages.
+// Used only in GenMarkdownTreeWithOpts.
+type GenMarkdownTreeOptions struct {
+	CommandSeparator string
+	FilePrepender    func(string) string
+	LinkHandler      func(string) string
+}
+
 func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(buf)
@@ -50,8 +66,8 @@ func GenMarkdown(cmd *cobra.Command, w io.Writer) error {
 	return GenMarkdownCustom(cmd, w, func(s string) string { return s })
 }
 
-// GenMarkdownCustom creates custom markdown output.
+// GenMarkdownWithOpts creates markdown output.
-func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+func GenMarkdownWithOpts(cmd *cobra.Command, opts GenMarkdownOptions) error {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
 
@@ -87,8 +103,8 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 			parent := cmd.Parent()
 			pname := parent.CommandPath()
 			link := pname + ".md"
-			link = strings.Replace(link, " ", "_", -1)
+			link = strings.Replace(link, " ", opts.CommandSeparator, -1)
-			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short))
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, opts.LinkHandler(link), parent.Short))
 			cmd.VisitParents(func(c *cobra.Command) {
 				if c.DisableAutoGenTag {
 					cmd.DisableAutoGenTag = c.DisableAutoGenTag
@@ -105,18 +121,27 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 			}
 			cname := name + " " + child.Name()
 			link := cname + ".md"
-			link = strings.Replace(link, " ", "_", -1)
+			link = strings.Replace(link, " ", opts.CommandSeparator, -1)
-			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short))
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, opts.LinkHandler(link), child.Short))
 		}
 		buf.WriteString("\n")
 	}
 	if !cmd.DisableAutoGenTag {
 		buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
 	}
-	_, err := buf.WriteTo(w)
+	_, err := buf.WriteTo(opts.Writer)
 	return err
 }
 
+// GenMarkdownCustom creates custom markdown output.
+func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	return GenMarkdownWithOpts(cmd, GenMarkdownOptions{
+		Writer:           w,
+		LinkHandler:      linkHandler,
+		CommandSeparator: "_",
+	})
+}
+
 // GenMarkdownTree will generate a markdown page for this command and all
 // descendants in the directory given. The header may be nil.
 // This function may not work correctly if your command names have `-` in them.
@@ -129,19 +154,18 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 	return GenMarkdownTreeCustom(cmd, dir, emptyStr, identity)
 }
 
-// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
+// GenMarkdownTreeWithOpts is the the same as GenMarkdownTree.
-// with custom filePrepender and linkHandler.
+func GenMarkdownTreeWithOpts(cmd *cobra.Command, dir string, opts GenMarkdownTreeOptions) error {
-func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
 	for _, c := range cmd.Commands() {
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
-		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
+		if err := GenMarkdownTreeWithOpts(c, dir, opts); err != nil {
 			return err
 		}
 	}
 
-	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
+	basename := strings.Replace(cmd.CommandPath(), " ", opts.CommandSeparator, -1) + ".md"
 	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {
@@ -149,11 +173,26 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
 	}
 	defer f.Close()
 
-	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+	if _, err := io.WriteString(f, opts.FilePrepender(filename)); err != nil {
 		return err
 	}
-	if err := GenMarkdownCustom(cmd, f, linkHandler); err != nil {
+	markdownOpts := GenMarkdownOptions{
+		Writer:           f,
+		LinkHandler:      opts.LinkHandler,
+		CommandSeparator: opts.CommandSeparator,
+	}
+	if err := GenMarkdownWithOpts(cmd, markdownOpts); err != nil {
 		return err
 	}
 	return nil
 }
+
+// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
+// with custom filePrepender and linkHandler.
+func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
+	return GenMarkdownTreeWithOpts(cmd, dir, GenMarkdownTreeOptions{
+		FilePrepender:    filePrepender,
+		LinkHandler:      linkHandler,
+		CommandSeparator: "_",
+	})
+}