Generate markdown for help topics

cmd/gen-docs/main.go

@@ -38,6 +38,7 @@ func main() {
 
 	io, _, _, _ := iostreams.Test()
 	rootCmd := root.NewCmdRoot(&cmdutil.Factory{IOStreams: io}, "", "")
+	rootCmd.InitDefaultHelpCmd()
 
 	err := os.MkdirAll(*dir, 0755)
 	if err != nil {

internal/docs/markdown.go

@@ -82,15 +82,22 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 // with custom filePrepender and linkHandler.
 func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
 	for _, c := range cmd.Commands() {
-		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
-			continue
+		if genMarkdown, ok := c.Annotations["markdown:generate"]; ok {
+			if genMarkdown == "false" {
+				continue
+			}
 		}
+
 		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
 			return err
 		}
 	}
 
 	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
+	if override, ok := cmd.Annotations["markdown:basename"]; ok {
+		basename = override + ".md"
+	}
+
 	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {

pkg/cmd/repo/credits/credits.go

@@ -61,6 +61,9 @@ func NewCmdCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *cobra.
 			return creditsRun(opts)
 		},
 		Hidden: true,
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmd.Flags().BoolVarP(&opts.Static, "static", "s", false, "Print a static version of the credits")
@@ -104,6 +107,9 @@ func NewCmdRepoCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *co
 			return creditsRun(opts)
 		},
 		Hidden: true,
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmd.Flags().BoolVarP(&opts.Static, "static", "s", false, "Print a static version of the credits")

pkg/cmd/repo/garden/garden.go

@@ -115,6 +115,9 @@ func NewCmdGarden(f *cmdutil.Factory, runF func(*GardenOptions) error) *cobra.Co
 			}
 			return gardenRun(&opts)
 		},
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	return cmd

pkg/cmd/root/help_topic.go

@@ -55,6 +55,9 @@ func NewHelpTopic(topic string) *cobra.Command {
 		Hidden: true,
 		Args:   cobra.NoArgs,
 		Run:    helpTopicHelpFunc,
+		Annotations: map[string]string{
+			"markdown:basename": "gh_help_" + topic,
+		},
 	}
 
 	cmd.SetHelpFunc(helpTopicHelpFunc)

pkg/cmd/version/version.go

@@ -16,6 +16,9 @@ func NewCmdVersion(f *cmdutil.Factory, version, buildDate string) *cobra.Command
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Fprint(f.IOStreams.Out, Format(version, buildDate))
 		},
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmdutil.DisableAuthCheck(cmd)