doc: GenMarkdown skip Synopsis on empty long cmd (#1207)

This patch modifies the GenMarkdownCustom to skip writing a Synopsis
header with the `cmd.Short` duplicated both before and after the header.

Instead, it only writes the `### Synopsis` header and the paragraph when
a `cmd.Long` has some kind of content in it.

Adds `TestGenMdDocWithNoLongOrSynopsis` as the test case.

Signed-off-by: Marc Lopez <marc5.12@outlook.com>

doc/cmd_test.go

@@ -27,7 +27,7 @@ func init() {
 	printCmd.Flags().BoolP("boolthree", "b", true, "help message for flag boolthree")
 
 	echoCmd.AddCommand(timesCmd, echoSubCmd, deprecatedCmd)
-	rootCmd.AddCommand(printCmd, echoCmd)
+	rootCmd.AddCommand(printCmd, echoCmd, dummyCmd)
 }
 
 var rootCmd = &cobra.Command{
@@ -73,6 +73,11 @@ var printCmd = &cobra.Command{
 	Long:  `an absolutely utterly useless command for testing.`,
 }
 
+var dummyCmd = &cobra.Command{
+	Use:   "dummy [action]",
+	Short: "Performs a dummy action",
+}
+
 func checkStringContains(t *testing.T, got, expected string) {
 	if !strings.Contains(got, expected) {
 		t.Errorf("Expected to contain: \n %v\nGot:\n %v\n", expected, got)

doc/md_docs.go

@@ -58,16 +58,12 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 	buf := new(bytes.Buffer)
 	name := cmd.CommandPath()
 
-	short := cmd.Short
-	long := cmd.Long
-	if len(long) == 0 {
-		long = short
-	}
-
 	buf.WriteString("## " + name + "\n\n")
-	buf.WriteString(short + "\n\n")
-	buf.WriteString("### Synopsis\n\n")
-	buf.WriteString(long + "\n\n")
+	buf.WriteString(cmd.Short + "\n\n")
+	if len(cmd.Long) > 0 {
+		buf.WriteString("### Synopsis\n\n")
+		buf.WriteString(cmd.Long + "\n\n")
+	}
 
 	if cmd.Runnable() {
 		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))

doc/md_docs_test.go

@@ -28,6 +28,20 @@ func TestGenMdDoc(t *testing.T) {
 	checkStringContains(t, output, "Options inherited from parent commands")
 }
 
+func TestGenMdDocWithNoLongOrSynopsis(t *testing.T) {
+	// We generate on subcommand so we have both subcommands and parents.
+	buf := new(bytes.Buffer)
+	if err := GenMarkdown(dummyCmd, buf); err != nil {
+		t.Fatal(err)
+	}
+	output := buf.String()
+
+	checkStringContains(t, output, dummyCmd.Example)
+	checkStringContains(t, output, dummyCmd.Short)
+	checkStringContains(t, output, "Options inherited from parent commands")
+	checkStringOmits(t, output, "### Synopsis")
+}
+
 func TestGenMdNoHiddenParents(t *testing.T) {
 	// We generate on subcommand so we have both subcommands and parents.
 	for _, name := range []string{"rootflag", "strtwo"} {