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>
This commit is contained in:
parent
9ed1d713d6
commit
02a0d2fbc9
@ -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)
|
||||
|
@ -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(cmd.Short + "\n\n")
|
||||
if len(cmd.Long) > 0 {
|
||||
buf.WriteString("### Synopsis\n\n")
|
||||
buf.WriteString(long + "\n\n")
|
||||
buf.WriteString(cmd.Long + "\n\n")
|
||||
}
|
||||
|
||||
if cmd.Runnable() {
|
||||
buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
|
||||
|
@ -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"} {
|
||||
|
Loading…
Reference in New Issue
Block a user