From c7ede29779e9dac8e473208a4fd2d3e6c35303c6 Mon Sep 17 00:00:00 2001 From: Sam Date: Thu, 22 Oct 2020 09:41:15 +0000 Subject: [PATCH 1/4] Refactor help topics to include short message --- pkg/cmd/root/help_topic.go | 84 ++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index d88109ad3..09566df2b 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -5,49 +5,53 @@ import ( "github.com/spf13/cobra" ) +var HelpTopics = map[string]map[string]string{ + "environment": { + "short": "Environmental 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, From f770c6481c99451167475edb88c7f33c5cf9d703 Mon Sep 17 00:00:00 2001 From: Sam Coe Date: Thu, 22 Oct 2020 14:01:08 +0200 Subject: [PATCH 2/4] Generate markdown for help topics --- cmd/gen-docs/main.go | 1 + internal/docs/markdown.go | 11 +++++++++-- pkg/cmd/repo/credits/credits.go | 6 ++++++ pkg/cmd/repo/garden/garden.go | 3 +++ pkg/cmd/root/help_topic.go | 3 +++ pkg/cmd/version/version.go | 3 +++ 6 files changed, 25 insertions(+), 2 deletions(-) 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..24ddf76a7 100644 --- a/internal/docs/markdown.go +++ b/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 { diff --git a/pkg/cmd/repo/credits/credits.go b/pkg/cmd/repo/credits/credits.go index ff6e44b5b..90aacbded 100644 --- a/pkg/cmd/repo/credits/credits.go +++ b/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") diff --git a/pkg/cmd/repo/garden/garden.go b/pkg/cmd/repo/garden/garden.go index 359d8d898..a3e8d5d16 100644 --- a/pkg/cmd/repo/garden/garden.go +++ b/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 diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 09566df2b..a47cb907e 100644 --- a/pkg/cmd/root/help_topic.go +++ b/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) diff --git a/pkg/cmd/version/version.go b/pkg/cmd/version/version.go index 040a3132e..d154717c7 100644 --- a/pkg/cmd/version/version.go +++ b/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) From 241e90aa9b85b95d0c9d8e5118bd9b0a67848f2c Mon Sep 17 00:00:00 2001 From: Sam Coe Date: Wed, 4 Nov 2020 12:35:08 +0300 Subject: [PATCH 3/4] Make markdown:generate annotation a markdown generation override for hidden commands --- internal/docs/markdown.go | 7 +++---- pkg/cmd/repo/credits/credits.go | 10 ++-------- pkg/cmd/repo/garden/garden.go | 3 --- pkg/cmd/root/help_topic.go | 1 + pkg/cmd/version/version.go | 3 --- 5 files changed, 6 insertions(+), 18 deletions(-) diff --git a/internal/docs/markdown.go b/internal/docs/markdown.go index 24ddf76a7..f9b8faeb9 100644 --- a/internal/docs/markdown.go +++ b/internal/docs/markdown.go @@ -82,10 +82,9 @@ 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 genMarkdown, ok := c.Annotations["markdown:generate"]; ok { - if genMarkdown == "false" { - continue - } + _, forceGeneration := c.Annotations["markdown:generate"] + if c.Hidden && !forceGeneration { + continue } if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil { diff --git a/pkg/cmd/repo/credits/credits.go b/pkg/cmd/repo/credits/credits.go index 90aacbded..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 `), @@ -61,9 +61,6 @@ 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") @@ -107,9 +104,6 @@ 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") diff --git a/pkg/cmd/repo/garden/garden.go b/pkg/cmd/repo/garden/garden.go index a3e8d5d16..359d8d898 100644 --- a/pkg/cmd/repo/garden/garden.go +++ b/pkg/cmd/repo/garden/garden.go @@ -115,9 +115,6 @@ func NewCmdGarden(f *cmdutil.Factory, runF func(*GardenOptions) error) *cobra.Co } return gardenRun(&opts) }, - Annotations: map[string]string{ - "markdown:generate": "false", - }, } return cmd diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index a47cb907e..95618f5c8 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -56,6 +56,7 @@ func NewHelpTopic(topic string) *cobra.Command { Args: cobra.NoArgs, Run: helpTopicHelpFunc, Annotations: map[string]string{ + "markdown:generate": "true", "markdown:basename": "gh_help_" + topic, }, } diff --git a/pkg/cmd/version/version.go b/pkg/cmd/version/version.go index d154717c7..040a3132e 100644 --- a/pkg/cmd/version/version.go +++ b/pkg/cmd/version/version.go @@ -16,9 +16,6 @@ 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) From 86906c67692df805016e58874970ec03893d774b Mon Sep 17 00:00:00 2001 From: Sam Coe Date: Wed, 4 Nov 2020 12:40:40 +0300 Subject: [PATCH 4/4] Small cleanup --- internal/docs/markdown.go | 4 ++-- pkg/cmd/root/help_topic.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/internal/docs/markdown.go b/internal/docs/markdown.go index f9b8faeb9..3432e9784 100644 --- a/internal/docs/markdown.go +++ b/internal/docs/markdown.go @@ -93,8 +93,8 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa } basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md" - if override, ok := cmd.Annotations["markdown:basename"]; ok { - basename = override + ".md" + if basenameOverride, found := cmd.Annotations["markdown:basename"]; found { + basename = basenameOverride + ".md" } filename := filepath.Join(dir, basename) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 95618f5c8..cffd452b9 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -7,7 +7,7 @@ import ( var HelpTopics = map[string]map[string]string{ "environment": { - "short": "Environmental variables that can be used with gh", + "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.