Skip to content

Commit

Permalink
markdown docs: add section 'Available commands'
Browse files Browse the repository at this point in the history
  • Loading branch information
deining committed Jun 30, 2023
1 parent dcb405a commit c771606
Show file tree
Hide file tree
Showing 3 changed files with 35 additions and 0 deletions.
19 changes: 19 additions & 0 deletions doc/md_docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,25 @@ 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))
Expand Down
3 changes: 3 additions & 0 deletions doc/md_docs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ 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")
}

Expand All @@ -52,6 +53,7 @@ func TestGenMdDocWithNoLongOrSynopsis(t *testing.T) {

checkStringContains(t, output, dummyCmd.Example)
checkStringContains(t, output, dummyCmd.Short)
checkStringContains(t, output, "Available commands")
checkStringContains(t, output, "Options inherited from parent commands")
checkStringOmits(t, output, "### Synopsis")
}
Expand All @@ -76,6 +78,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")
}

Expand Down
13 changes: 13 additions & 0 deletions doc/util.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down

0 comments on commit c771606

Please sign in to comment.