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 Jul 1, 2023
1 parent dcb405a commit ddea02e
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 1 deletion.
18 changes: 18 additions & 0 deletions doc/md_docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
4 changes: 3 additions & 1 deletion doc/md_docs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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")
}

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 ddea02e

Please sign in to comment.