update generated content for man pages and website

Hoteld · May 17, 2024 · 39e4cbd · 39e4cbd
1 parent 77f964a
commit 39e4cbd
Show file tree

Hide file tree

Showing 7 changed files with 61 additions and 4 deletions.
diff --git a/internal/docs/docs_test.go b/internal/docs/docs_test.go
@@ -28,6 +28,8 @@ func init() {
 
 	jsonCmd.Flags().StringSlice("json", nil, "help message for flag json")
 
+	aliasCmd.Flags().StringSlice("yang", nil, "help message for flag yang")
+
 	echoCmd.AddCommand(timesCmd, echoSubCmd, deprecatedCmd)
 	rootCmd.AddCommand(printCmd, echoCmd, dummyCmd)
 }
@@ -75,6 +77,13 @@ var printCmd = &cobra.Command{
 	Long:  `an absolutely utterly useless command for testing.`,
 }
 
+var aliasCmd = &cobra.Command{
+	Use:     "ying [yang]",
+	Short:   "The ying and yang of it all",
+	Long:    "an absolutely utterly useless command for testing aliases!.",
+	Aliases: []string{"yoo", "foo"},
+}
+
 var jsonCmd = &cobra.Command{
 	Use:   "blah --json <fields>",
 	Short: "View details in JSON",

diff --git a/internal/docs/man.go b/internal/docs/man.go
@@ -179,6 +179,14 @@ func manPrintOptions(buf *bytes.Buffer, command *cobra.Command) {
 	}
 }
 
+func manPrintAliases(buf *bytes.Buffer, command *cobra.Command) {
+	if len(command.Aliases) > 0 {
+		buf.WriteString("# ALIASES\n")
+		buf.WriteString(strings.Join(root.BuildAliasList(command, command.Aliases), ", "))
+		buf.WriteString("\n")
+	}
+}
+
 func manPrintJSONFields(buf *bytes.Buffer, command *cobra.Command) {
 	raw, ok := command.Annotations["help:json-fields"]
 	if !ok {
@@ -207,6 +215,7 @@ func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
 		}
 	}
 	manPrintOptions(buf, cmd)
+	manPrintAliases(buf, cmd)
 	manPrintJSONFields(buf, cmd)
 	if len(cmd.Example) > 0 {
 		buf.WriteString("# EXAMPLE\n")

diff --git a/internal/docs/man_test.go b/internal/docs/man_test.go
@@ -98,6 +98,21 @@ func TestGenManSeeAlso(t *testing.T) {
 	}
 }
 
+func TestGenManAliases(t *testing.T) {
+	buf := new(bytes.Buffer)
+	header := &GenManHeader{}
+	if err := renderMan(aliasCmd, header, buf); err != nil {
+		t.Fatal(err)
+	}
+
+	output := buf.String()
+
+	checkStringContains(t, output, translate(aliasCmd.Name()))
+	checkStringContains(t, output, "ALIASES")
+	checkStringContains(t, output, "foo")
+	checkStringContains(t, output, "yoo")
+}
+
 func TestGenManJSONFields(t *testing.T) {
 	buf := new(bytes.Buffer)
 	header := &GenManHeader{}

diff --git a/internal/docs/markdown.go b/internal/docs/markdown.go
@@ -26,6 +26,15 @@ func printJSONFields(w io.Writer, cmd *cobra.Command) {
 	fmt.Fprint(w, "\n\n")
 }
 
+func printAliases(w io.Writer, cmd *cobra.Command) {
+	if len(cmd.Aliases) > 0 {
+		fmt.Fprintf(w, "### ALIASES\n\n")
+		fmt.Fprint(w, text.FormatSlice(strings.Split(strings.Join(root.BuildAliasList(cmd, cmd.Aliases), ", "), ","), 0, 0, "", "", true))
+		fmt.Fprint(w, "\n\n")
+	}
+
+}
+
 func printOptions(w io.Writer, cmd *cobra.Command) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(w)
@@ -147,6 +156,7 @@ func genMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 	if err := printOptions(w, cmd); err != nil {
 		return err
 	}
+	printAliases(w, cmd)
 	printJSONFields(w, cmd)
 	fmt.Fprint(w, "{% endraw %}\n")
 

diff --git a/internal/docs/markdown_test.go b/internal/docs/markdown_test.go
@@ -70,6 +70,20 @@ func TestGenMdNoHiddenParents(t *testing.T) {
 	checkStringOmits(t, output, "Options inherited from parent commands")
 }
 
+func TestGenMdAliases(t *testing.T) {
+	buf := new(bytes.Buffer)
+	if err := genMarkdownCustom(aliasCmd, buf, nil); err != nil {
+		t.Fatal(err)
+	}
+	output := buf.String()
+
+	checkStringContains(t, output, aliasCmd.Long)
+	checkStringContains(t, output, jsonCmd.Example)
+	checkStringContains(t, output, "ALIASES")
+	checkStringContains(t, output, "yoo")
+	checkStringContains(t, output, "foo")
+}
+
 func TestGenMdJSONFields(t *testing.T) {
 	buf := new(bytes.Buffer)
 	if err := genMarkdownCustom(jsonCmd, buf, nil); err != nil {

diff --git a/pkg/cmd/root/help.go b/pkg/cmd/root/help.go
@@ -132,7 +132,7 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, args []string) {
 	helpEntries = append(helpEntries, helpEntry{"USAGE", command.UseLine()})
 
 	if len(command.Aliases) > 0 {
-		helpEntries = append(helpEntries, helpEntry{"ALIASES", strings.Join(buildAliasList(command, command.Aliases), ", ") + "\n"})
+		helpEntries = append(helpEntries, helpEntry{"ALIASES", strings.Join(BuildAliasList(command, command.Aliases), ", ") + "\n"})
 	}
 
 	for _, g := range GroupedCommands(command) {
@@ -303,7 +303,7 @@ func dedent(s string) string {
 	return strings.TrimSuffix(buf.String(), "\n")
 }
 
-func buildAliasList(cmd *cobra.Command, aliases []string) []string {
+func BuildAliasList(cmd *cobra.Command, aliases []string) []string {
 	if !cmd.HasParent() {
 		return aliases
 	}
@@ -321,5 +321,5 @@ func buildAliasList(cmd *cobra.Command, aliases []string) []string {
 		}
 	}
 
-	return buildAliasList(cmd.Parent(), aliasesWithParentAliases)
+	return BuildAliasList(cmd.Parent(), aliasesWithParentAliases)
 }
diff --git a/pkg/cmd/root/help_reference.go b/pkg/cmd/root/help_reference.go
@@ -65,7 +65,7 @@ func cmdRef(w io.Writer, cmd *cobra.Command, depth int) {
 	// Aliases
 	if len(cmd.Aliases) > 0 {
 		fmt.Fprintf(w, "%s\n\n", "Aliases")
-		fmt.Fprintf(w, "\n%s\n\n", dedent(strings.Join(buildAliasList(cmd, cmd.Aliases), ", ")))
+		fmt.Fprintf(w, "\n%s\n\n", dedent(strings.Join(BuildAliasList(cmd, cmd.Aliases), ", ")))
 	}
 
 	// Subcommands