From ddea02ea6b820293ef772640a765caa915bd7b14 Mon Sep 17 00:00:00 2001
From: Andreas Deininger <andreas@deininger.net>
Date: Fri, 30 Jun 2023 23:15:42 +0200
Subject: [PATCH] markdown docs: add section 'Available commands'

---
 doc/md_docs.go      | 18 ++++++++++++++++++
 doc/md_docs_test.go |  4 +++-
 doc/util.go         | 13 +++++++++++++
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc/md_docs.go b/doc/md_docs.go
index c4a27c00..58d78f16 100644
--- a/doc/md_docs.go
+++ b/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))
diff --git a/doc/md_docs_test.go b/doc/md_docs_test.go
index e70cad82..9f4e968c 100644
--- a/doc/md_docs_test.go
+++ b/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")
 }
 
diff --git a/doc/util.go b/doc/util.go
index 0aaa07a1..8fc2657e 100644
--- a/doc/util.go
+++ b/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 {