markdown docs: add section 'Available commands'

doc/md_docs.go

@@ -70,6 +70,24 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
 	}
 
+	if HasSubCommand(cmd) {
+		buf.WriteString("### Available commands\n\n")
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			cname := name + " " + child.Name()
+			link := cname + ".md"
+			link = strings.ReplaceAll(link, " ", "_")
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", child.Name(), linkHandler(link), child.Short))
+		}
+		buf.WriteString("\n")
+	}
+
 	if len(cmd.Example) > 0 {
 		buf.WriteString("### Examples\n\n")
 		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))

doc/md_docs_test.go

@@ -39,11 +39,12 @@ func TestGenMdDoc(t *testing.T) {
 	checkStringContains(t, output, rootCmd.Short)
 	checkStringContains(t, output, echoSubCmd.Short)
 	checkStringOmits(t, output, deprecatedCmd.Short)
+	checkStringContains(t, output, "Available commands")
 	checkStringContains(t, output, "Options inherited from parent commands")
 }
 
 func TestGenMdDocWithNoLongOrSynopsis(t *testing.T) {
-	// We generate on subcommand so we have both subcommands and parents.
+	// Use a simple subcommand without long and without synopsis, no own subcommands.
 	buf := new(bytes.Buffer)
 	if err := GenMarkdown(dummyCmd, buf); err != nil {
 		t.Fatal(err)
@@ -76,6 +77,7 @@ func TestGenMdNoHiddenParents(t *testing.T) {
 	checkStringContains(t, output, rootCmd.Short)
 	checkStringContains(t, output, echoSubCmd.Short)
 	checkStringOmits(t, output, deprecatedCmd.Short)
+	checkStringContains(t, output, "Available commands")
 	checkStringOmits(t, output, "Options inherited from parent commands")
 }
 

doc/util.go

@@ -36,6 +36,19 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 	return false
 }
 
+// Test to see if a given command has one or more subcommands
+// Basically this is a test for a subcommand which is both not
+// deprecated and not the autogenerated help command.
+func HasSubCommand(cmd *cobra.Command) bool {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
 // Temporary workaround for yaml lib generating incorrect yaml with long strings
 // that do not contain \n.
 func forceMultiLine(s string) string {