diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go index c108485c3..5698794e0 100644 --- a/cmd/gen-docs/main.go +++ b/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 { diff --git a/internal/docs/markdown.go b/internal/docs/markdown.go index 983a7cd7b..3432e9784 100644 --- a/internal/docs/markdown.go +++ b/internal/docs/markdown.go @@ -82,15 +82,21 @@ 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() { + _, forceGeneration := c.Annotations["markdown:generate"] + if c.Hidden && !forceGeneration { continue } + if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil { return err } } basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md" + if basenameOverride, found := cmd.Annotations["markdown:basename"]; found { + basename = basenameOverride + ".md" + } + filename := filepath.Join(dir, basename) f, err := os.Create(filename) if err != nil { diff --git a/pkg/cmd/repo/credits/credits.go b/pkg/cmd/repo/credits/credits.go index ff6e44b5b..e792b54d6 100644 --- a/pkg/cmd/repo/credits/credits.go +++ b/pkg/cmd/repo/credits/credits.go @@ -45,10 +45,10 @@ func NewCmdCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *cobra. Example: heredoc.Doc(` # see a credits animation for this project $ gh credits - + # display a non-animated thank you $ gh credits -s - + # just print the contributors, one per line $ gh credits | cat `), diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index d88109ad3..cffd452b9 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -5,52 +5,60 @@ import ( "github.com/spf13/cobra" ) +var HelpTopics = map[string]map[string]string{ + "environment": { + "short": "Environment variables that can be used with gh", + "long": heredoc.Doc(` + GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids + being prompted to authenticate and takes precedence over previously stored credentials. + + GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise. + + GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands + that otherwise operate on a local repository. + + GH_HOST: specify the GitHub hostname for commands that would otherwise assume + the "github.com" host when not in a context of an existing repository. + + GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use + for authoring text. + + BROWSER: the web browser to use for opening links. + + DEBUG: set to any value to enable verbose output to standard error. Include values "api" + or "oauth" to print detailed information about HTTP requests or authentication flow. + + GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output to, e.g. "less". + + GLAMOUR_STYLE: the style to use for rendering Markdown. See + https://github.com/charmbracelet/glamour#styles + + NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output. + + CLICOLOR: set to "0" to disable printing ANSI colors in output. + + CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output + even when the output is piped. + + GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh + checks for new releases once every 24 hours and displays an upgrade notice on standard + error if a newer version was found. + `), + }, +} + func NewHelpTopic(topic string) *cobra.Command { - topicContent := make(map[string]string) - - topicContent["environment"] = heredoc.Doc(` - GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids - being prompted to authenticate and takes precedence over previously stored credentials. - - GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise. - - GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands - that otherwise operate on a local repository. - - GH_HOST: specify the GitHub hostname for commands that would otherwise assume - the "github.com" host when not in a context of an existing repository. - - GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use - for authoring text. - - BROWSER: the web browser to use for opening links. - - DEBUG: set to any value to enable verbose output to standard error. Include values "api" - or "oauth" to print detailed information about HTTP requests or authentication flow. - - GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output to, e.g. "less". - - GLAMOUR_STYLE: the style to use for rendering Markdown. See - https://github.com/charmbracelet/glamour#styles - - NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output. - - CLICOLOR: set to "0" to disable printing ANSI colors in output. - - CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output - even when the output is piped. - - GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh - checks for new releases once every 24 hours and displays an upgrade notice on standard - error if a newer version was found. - `) - cmd := &cobra.Command{ Use: topic, - Long: topicContent[topic], + Short: HelpTopics[topic]["short"], + Long: HelpTopics[topic]["long"], Hidden: true, Args: cobra.NoArgs, Run: helpTopicHelpFunc, + Annotations: map[string]string{ + "markdown:generate": "true", + "markdown:basename": "gh_help_" + topic, + }, } cmd.SetHelpFunc(helpTopicHelpFunc)