STACKITGit/cli
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #2257 from cli/gen-help-docs

Browse source 
Generate markdown docs for help topics
This commit is contained in:
Nate Smith 2020-11-04 13:04:47 -06:00 • committed by GitHub
commit 9edcd686e2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 58 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

1
cmd/gen-docs/main.go
View file

@ -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 {

8
internal/docs/markdown.go
View file

@ -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 {

4
pkg/cmd/repo/credits/credits.go
View file

@ -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
`),

88
pkg/cmd/root/help_topic.go
View file

@ -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)