📝 Use heredoc for docs

stoe · Mar 19, 2023 · 10b80af · 10b80af
1 parent 3b8e3f7
commit 10b80af
Show file tree

Hide file tree

Showing 9 changed files with 69 additions and 23 deletions.
diff --git a/cmd/actions.go b/cmd/actions.go
@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/pterm/pterm"
 	"github.com/shurcooL/graphql"
 	"github.com/spf13/cobra"
@@ -37,8 +38,11 @@ var (
 	ActionsCmd = &cobra.Command{
 		Use:   "actions",
 		Short: "Report on GitHub Actions",
-		Long:  "Report on GitHub Actions",
-		RunE:  GetActionsReport,
+		Long: heredoc.Docf(
+			`Report on GitHub Actions, requires %s scope`,
+			utils.HiBlack("repo"),
+		),
+		RunE: GetActionsReport,
 	}
 
 	exclude       = false

diff --git a/cmd/billing.go b/cmd/billing.go
@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/pterm/pterm"
 	"github.com/shurcooL/graphql"
 	"github.com/spf13/cobra"
@@ -36,8 +37,12 @@ var (
 	BillingCmd = &cobra.Command{
 		Use:   "billing",
 		Short: "Report on GitHub billing",
-		Long:  "Report on GitHub billing",
-		RunE:  GetBilling,
+		Long: heredoc.Docf(
+			`Report on GitHub billing, requires %s and/or %s scope`,
+			utils.HiBlack("read:enterprise"),
+			utils.HiBlack("read:org"),
+		),
+		RunE: GetBilling,
 	}
 
 	all      bool

diff --git a/cmd/license.go b/cmd/license.go
@@ -25,6 +25,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/fatih/color"
 	"github.com/pterm/pterm"
 	"github.com/spf13/cobra"
@@ -35,8 +36,12 @@ var (
 	LicenseCmd = &cobra.Command{
 		Use:   "license",
 		Short: "Report on GitHub Enterprise licensing",
-		Long:  "Report on GitHub Enterprise licensing",
-		RunE:  GetLicensing,
+		Long: heredoc.Docf(
+			`Report on GitHub Enterprise licensing, requires %s and %s scope`,
+			utils.HiBlack("read:enterprise"),
+			utils.HiBlack("user:email"),
+		),
+		RunE: GetLicensing,
 	}
 
 	licenseData LicenseData

diff --git a/cmd/repo.go b/cmd/repo.go
@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/pterm/pterm"
 	"github.com/shurcooL/graphql"
 	"github.com/spf13/cobra"
@@ -40,9 +41,13 @@ var (
 	RepoCmd = &cobra.Command{
 		Use:   "repo",
 		Short: "Report on GitHub repositories",
-		Long:  "Report on GitHub repositories",
-		RunE:  GetRepos,
+		Long: heredoc.Docf(
+			`Report on GitHub repositories, requires %s and/or %s scope`,
+			utils.HiBlack("read:enterprise"),
+			utils.HiBlack("read:org"),
+		),
 		Aliases: []string{"repos"},
+		RunE:    GetRepos,
 	}
 
 	orgRepositoriesQuery struct {

diff --git a/cmd/root.go b/cmd/root.go
@@ -27,6 +27,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/briandowns/spinner"
 	"github.com/cli/go-gh"
 	"github.com/cli/go-gh/pkg/api"
@@ -64,7 +65,7 @@ var (
 	RootCmd = &cobra.Command{
 		Use:               "gh-report",
 		Short:             "gh cli extension to generate reports",
-		Long:              `gh cli extension to generate enterprise/organization/user/repository reports`,
+		Long:              "gh cli extension to generate enterprise/organization/user/repository reports",
 		Version:           "2.1.0",
 		PersistentPreRunE: run,
 	}
@@ -101,12 +102,31 @@ func Execute() {
 func init() {
 	cobra.OnInitialize(initConfig)
 
-	RootCmd.PersistentFlags().BoolVar(&noCache, "no-cache", false, "do not cache results for one hour (default: false)")
-	RootCmd.PersistentFlags().BoolVar(&silent, "silent", false, "do not print any output (default: false)")
-
-	RootCmd.PersistentFlags().StringVarP(&enterprise, "enterprise", "e", "", "GitHub Enterprise Cloud account")
-	RootCmd.PersistentFlags().StringVarP(&owner, "owner", "o", "", "GitHub account (organization or user account)")
-	RootCmd.PersistentFlags().StringVarP(&repo, "repo", "r", "", "GitHub repository (owner/repo)")
+	RootCmd.PersistentFlags().BoolVar(&noCache, "no-cache", false, "Do not cache results for one hour (default: false)")
+	RootCmd.PersistentFlags().BoolVar(&silent, "silent", false, "Do not print any output (default: false)")
+
+	RootCmd.PersistentFlags().StringVarP(
+		&enterprise, "enterprise", "e", "",
+		heredoc.Docf(
+			`GitHub Enterprise Cloud account (requires %s scope)`,
+			utils.HiBlack("read:enterprise"),
+		),
+	)
+	RootCmd.PersistentFlags().StringVarP(
+		&owner, "owner", "o", "",
+		heredoc.Docf(
+			`GitHub account organization (requires %s scope) or user account (requires %s scope)`,
+			utils.HiBlack("read:org"),
+			utils.HiBlack("n/a"),
+		),
+	)
+	RootCmd.PersistentFlags().StringVarP(
+		&repo, "repo", "r", "",
+		heredoc.Docf(
+			`GitHub repository (owner/repo), requires %s scope`,
+			utils.HiBlack("repo"),
+		),
+	)
 
 	RootCmd.PersistentFlags().StringVarP(&token, "token", "t", "", "GitHub Personal Access Token (default: gh auth token)")
 	RootCmd.PersistentFlags().StringVar(&hostname, "hostname", "", "GitHub Enterprise Server hostname")

diff --git a/cmd/verified_emails.go b/cmd/verified_emails.go
@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/pterm/pterm"
 	"github.com/shurcooL/graphql"
 	"github.com/spf13/cobra"
@@ -36,9 +37,14 @@ var (
 	VerifiedEmailsCmd = &cobra.Command{
 		Use:   "verified-emails",
 		Short: "List enterprise/organization members' verified emails",
-		Long:  "List enterprise/organization members' verified emails",
-		RunE:  GetUserEmails,
+		Long: heredoc.Docf(
+			`List enterprise/organization members' verified emails, requires %s, %s and/or %s scope`,
+			utils.HiBlack("user:email"),
+			utils.HiBlack("read:enterprise"),
+			utils.HiBlack("read:org"),
+		),
 		Aliases: []string{"emails", "email"},
+		RunE:    GetUserEmails,
 	}
 
 	memberQuery struct {

diff --git a/go.mod b/go.mod
@@ -3,6 +3,7 @@ module github.com/stoe/gh-report
 go 1.20
 
 require (
+	github.com/MakeNowJust/heredoc v1.0.0
 	github.com/briandowns/spinner v1.23.0
 	github.com/cli/go-gh v1.2.1
 	github.com/fatih/color v1.15.0

diff --git a/go.sum b/go.sum
@@ -4,6 +4,7 @@ atomicgo.dev/cursor v0.1.1/go.mod h1:Lr4ZJB3U7DfPPOkbH7/6TOtJ4vFGHlgj1nc+n900IpU
 atomicgo.dev/keyboard v0.2.9 h1:tOsIid3nlPLZ3lwgG8KZMp/SFmr7P0ssEN5JUsm78K8=
 atomicgo.dev/keyboard v0.2.9/go.mod h1:BC4w9g00XkxH/f1HXhW2sXmJFOCWbKn9xrOunSFtExQ=
 github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
+github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/MarvinJWendt/testza v0.1.0/go.mod h1:7AxNvlfeHP7Z/hDQ5JtE3OKYT3XFUeLCDE2DQninSqs=
 github.com/MarvinJWendt/testza v0.2.1/go.mod h1:God7bhG8n6uQxwdScay+gjm9/LnO4D3kkcZX4hv9Rp8=
 github.com/MarvinJWendt/testza v0.2.8/go.mod h1:nwIcjmr0Zz+Rcwfh3/4UhBp7ePKVhuBExvZqnKYWlII=

diff --git a/readme.md b/readme.md
@@ -33,15 +33,14 @@ Available Commands:
 
 Flags:
       --csv string          Path to CSV file
-  -e, --enterprise string   GitHub Enterprise Cloud account
+  -e, --enterprise string   GitHub Enterprise Cloud account (requires read:enterprise scope)
   -h, --help                help for gh-report
       --hostname string     GitHub Enterprise Server hostname
       --json string         Path to JSON file
-      --no-cache            do not cache results for one hour (default: false)
-  -o, --owner string        GitHub account (organization or user account)
-  -r, --repo string         GitHub repository (owner/repo)
-      --silent              do not print any output (default: false)
-      --token string        GitHub Personal Access Token (default: gh auth token)
+      --no-cache            Do not cache results for one hour (default: false)
+  -o, --owner string        GitHub account organization (requires read:org scope) or user account (requires n/a scope)
+  -r, --repo string         GitHub repository (owner/repo), requires repo scope
+      --silent              Do not print any output (default: false)
   -t, --token string        GitHub Personal Access Token (default: gh auth token)
   -v, --version             version for gh-report