doc: Cleanup md_docs

Performance gain:
benchmark                        old ns/op     new ns/op     delta
BenchmarkGenMarkdownToFile-4     23096         10295         -55.43%

benchmark                        old allocs     new allocs     delta
BenchmarkGenMarkdownToFile-4     47             48             +2.13%

benchmark                        old bytes     new bytes     delta
BenchmarkGenMarkdownToFile-4     1984          2832          +42.74%

doc/md_docs.go

@@ -14,6 +14,7 @@
 package doc
 
 import (
+	"bytes"
 	"fmt"
 	"io"
 	"os"
@@ -25,29 +26,21 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func printOptions(w io.Writer, cmd *cobra.Command, name string) error {
+func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
 	flags := cmd.NonInheritedFlags()
-	flags.SetOutput(w)
+	flags.SetOutput(buf)
 	if flags.HasFlags() {
-		if _, err := fmt.Fprintf(w, "### Options\n\n```\n"); err != nil {
+		buf.WriteString("### Options\n\n```\n")
-			return err
-		}
 		flags.PrintDefaults()
-		if _, err := fmt.Fprintf(w, "```\n\n"); err != nil {
+		buf.WriteString("```\n\n")
-			return err
-		}
 	}
 
 	parentFlags := cmd.InheritedFlags()
-	parentFlags.SetOutput(w)
+	parentFlags.SetOutput(buf)
 	if parentFlags.HasFlags() {
-		if _, err := fmt.Fprintf(w, "### Options inherited from parent commands\n\n```\n"); err != nil {
+		buf.WriteString("### Options inherited from parent commands\n\n```\n")
-			return err
-		}
 		parentFlags.PrintDefaults()
-		if _, err := fmt.Fprintf(w, "```\n\n"); err != nil {
+		buf.WriteString("```\n\n")
-			return err
-		}
 	}
 	return nil
 }
@@ -59,6 +52,7 @@ func GenMarkdown(cmd *cobra.Command, w io.Writer) error {
 
 // GenMarkdownCustom creates custom markdown output.
 func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	buf := new(bytes.Buffer)
 	name := cmd.CommandPath()
 
 	short := cmd.Short
@@ -67,49 +61,31 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 		long = short
 	}
 
-	if _, err := fmt.Fprintf(w, "## %s\n\n", name); err != nil {
+	buf.WriteString("## " + name + "\n\n")
-		return err
+	buf.WriteString(short + "\n\n")
-	}
+	buf.WriteString("### Synopsis\n\n")
-	if _, err := fmt.Fprintf(w, "%s\n\n", short); err != nil {
+	buf.WriteString("\n" + long + "\n\n")
-		return err
-	}
-	if _, err := fmt.Fprintf(w, "### Synopsis\n\n"); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(w, "\n%s\n\n", long); err != nil {
-		return err
-	}
 
 	if cmd.Runnable() {
-		if _, err := fmt.Fprintf(w, "```\n%s\n```\n\n", cmd.UseLine()); err != nil {
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
-			return err
-		}
 	}
 
 	if len(cmd.Example) > 0 {
-		if _, err := fmt.Fprintf(w, "### Examples\n\n"); err != nil {
+		buf.WriteString("### Examples\n\n")
-			return err
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))
-		}
-		if _, err := fmt.Fprintf(w, "```\n%s\n```\n\n", cmd.Example); err != nil {
-			return err
-		}
 	}
 
-	if err := printOptions(w, cmd, name); err != nil {
+	if err := printOptions(buf, cmd, name); err != nil {
 		return err
 	}
 	if hasSeeAlso(cmd) {
-		if _, err := fmt.Fprintf(w, "### SEE ALSO\n"); err != nil {
+		buf.WriteString("### SEE ALSO\n")
-			return err
-		}
 		if cmd.HasParent() {
 			parent := cmd.Parent()
 			pname := parent.CommandPath()
 			link := pname + ".md"
 			link = strings.Replace(link, " ", "_", -1)
-			if _, err := fmt.Fprintf(w, "* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short); err != nil {
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short))
-				return err
-			}
 			cmd.VisitParents(func(c *cobra.Command) {
 				if c.DisableAutoGenTag {
 					cmd.DisableAutoGenTag = c.DisableAutoGenTag
@@ -127,21 +103,16 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 			cname := name + " " + child.Name()
 			link := cname + ".md"
 			link = strings.Replace(link, " ", "_", -1)
-			if _, err := fmt.Fprintf(w, "* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short); err != nil {
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short))
-				return err
-			}
-		}
-		if _, err := fmt.Fprintf(w, "\n"); err != nil {
-			return err
 		}
+		buf.WriteString("\n")
 	}
 	if !cmd.DisableAutoGenTag {
-		if _, err := fmt.Fprintf(w, "###### Auto generated by spf13/cobra on %s\n", time.Now().Format("2-Jan-2006")); err != nil {
+		buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
+	}
+	_, err := buf.WriteTo(w)
 	return err
 }
-	}
-	return nil
-}
 
 // GenMarkdownTree will generate a markdown page for this command and all
 // descendants in the directory given. The header may be nil.

doc/md_docs_test.go

@@ -105,3 +105,20 @@ func TestGenMdTree(t *testing.T) {
 		t.Fatalf("Expected file 'do.md' to exist")
 	}
 }
+
+func BenchmarkGenMarkdownToFile(b *testing.B) {
+	c := initializeWithRootCmd()
+	file, err := ioutil.TempFile("", "")
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer os.Remove(file.Name())
+	defer file.Close()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if err := GenMarkdown(c, file); err != nil {
+			b.Fatal(err)
+		}
+	}
+}