📝 Use auto-generated docs

stoe · Mar 25, 2023 · b2335c4 · b2335c4
1 parent 5e5905c
commit b2335c4
Show file tree

Hide file tree

Showing 17 changed files with 280 additions and 58 deletions.
diff --git a/cmd/actions.go b/cmd/actions.go
@@ -39,8 +39,8 @@ var (
 		Use:   "actions",
 		Short: "Report on GitHub Actions",
 		Long: heredoc.Docf(
-			`Report on GitHub Actions, requires %s scope`,
-			utils.HiBlack("repo"),
+			`Report on GitHub Actions, requires %[1]srepo%[1]s scope`,
+			"`",
 		),
 		RunE: GetActionsReport,
 	}

diff --git a/cmd/billing.go b/cmd/billing.go
@@ -38,9 +38,8 @@ var (
 		Use:   "billing",
 		Short: "Report on GitHub billing",
 		Long: heredoc.Docf(
-			`Report on GitHub billing, requires %s and/or %s scope`,
-			utils.HiBlack("read:enterprise"),
-			utils.HiBlack("read:org"),
+			`Report on GitHub billing, requires %[1]sread:enterprise%[1]s and/or %[1]sread:org%[1]s scope`,
+			"`",
 		),
 		RunE: GetBilling,
 	}

diff --git a/cmd/root.go → cmd/cmd.go b/cmd/root.go → cmd/cmd.go
@@ -64,7 +64,7 @@ var (
 	sp = spinner.New(spinner.CharSets[14], 40*time.Millisecond)
 
 	RootCmd = &cobra.Command{
-		Use:               "gh-report",
+		Use:               "report",
 		Short:             "gh cli extension to generate reports",
 		Long:              "gh cli extension to generate enterprise/organization/user/repository reports",
 		Version:           "2.2.0",
@@ -111,23 +111,22 @@ func init() {
 	RootCmd.PersistentFlags().StringVarP(
 		&enterprise, "enterprise", "e", "",
 		heredoc.Docf(
-			`GitHub Enterprise Cloud account (requires %s scope)`,
-			utils.HiBlack("read:enterprise"),
+			`GitHub Enterprise Cloud account (requires %[1]sread:enterprise%[1]s scope)`,
+			"`",
 		),
 	)
 	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"),
+			`GitHub account organization (requires %[1]sread:org%[1]s scope) or user account (requires %[1]sn/a%[1]s scope)`,
+			"`",
 		),
 	)
 	RootCmd.PersistentFlags().StringVarP(
 		&repo, "repo", "r", "",
 		heredoc.Docf(
-			`GitHub repository (owner/repo), requires %s scope`,
-			utils.HiBlack("repo"),
+			`GitHub repository (owner/repo), requires %[1]srepo%[1]s scope`,
+			"`",
 		),
 	)
 

diff --git a/cmd/root_test.go → cmd/cmd_test.go b/cmd/root_test.go → cmd/cmd_test.go
diff --git a/cmd/license.go b/cmd/license.go
@@ -36,9 +36,8 @@ var (
 		Use:   "license",
 		Short: "Report on GitHub Enterprise licensing",
 		Long: heredoc.Docf(
-			`Report on GitHub Enterprise licensing, requires %s and %s scope`,
-			utils.HiBlack("read:enterprise"),
-			utils.HiBlack("user:email"),
+			`Report on GitHub Enterprise licensing, requires %[1]sread:enterprise%[1]s and %[1]suser:email%[1]s scope`,
+			"`",
 		),
 		RunE: GetLicensing,
 	}

diff --git a/cmd/repo.go b/cmd/repo.go
@@ -42,9 +42,8 @@ var (
 		Use:   "repo",
 		Short: "Report on GitHub repositories",
 		Long: heredoc.Docf(
-			`Report on GitHub repositories, requires %s and/or %s scope`,
-			utils.HiBlack("read:enterprise"),
-			utils.HiBlack("read:org"),
+			`Report on GitHub repositories, requires %[1]sread:enterprise%[1]s and/or %[1]sread:org%[1]s scope`,
+			"`",
 		),
 		Aliases: []string{"repos"},
 		RunE:    GetRepos,

diff --git a/cmd/verified_emails.go b/cmd/verified_emails.go
@@ -38,10 +38,8 @@ var (
 		Use:   "verified-emails",
 		Short: "List enterprise/organization members' verified emails",
 		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"),
+			`List enterprise/organization members' verified emails, requires %[1]suser:email%[1]s, %[1]sread:enterprise%[1]s and/or %[1]sread:org%[1]s scope`,
+			"`",
 		),
 		Aliases: []string{"emails", "email"},
 		RunE:    GetUserEmails,

diff --git a/docs/report.md b/docs/report.md
@@ -0,0 +1,33 @@
+## report
+
+gh cli extension to generate reports
+
+### Synopsis
+
+gh cli extension to generate enterprise/organization/user/repository reports
+
+### Options
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+  -h, --help                         help for report
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report actions](report_actions.md)	 - Report on GitHub Actions
+* [report billing](report_billing.md)	 - Report on GitHub billing
+* [report license](report_license.md)	 - Report on GitHub Enterprise licensing
+* [report repo](report_repo.md)	 - Report on GitHub repositories
+* [report verified-emails](report_verified-emails.md)	 - List enterprise/organization members' verified emails
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/docs/report_actions.md b/docs/report_actions.md
@@ -0,0 +1,39 @@
+## report actions
+
+Report on GitHub Actions
+
+### Synopsis
+
+Report on GitHub Actions, requires `repo` scope
+
+```
+report actions [flags]
+```
+
+### Options
+
+```
+      --exclude   Exclude Github Actions authored by GitHub
+  -h, --help      help for actions
+```
+
+### Options inherited from parent commands
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report](report.md)	 - gh cli extension to generate reports
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/docs/report_billing.md b/docs/report_billing.md
@@ -0,0 +1,43 @@
+## report billing
+
+Report on GitHub billing
+
+### Synopsis
+
+Report on GitHub billing, requires `read:enterprise` and/or `read:org` scope
+
+```
+report billing [flags]
+```
+
+### Options
+
+```
+      --actions    Get GitHub Actions billing
+      --all        Get all billing data (default true)
+  -h, --help       help for billing
+      --packages   Get GitHub Packages billing
+      --security   Get GitHub Advanced Security active committers
+      --storage    Get shared storage billing
+```
+
+### Options inherited from parent commands
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report](report.md)	 - gh cli extension to generate reports
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/docs/report_license.md b/docs/report_license.md
@@ -0,0 +1,38 @@
+## report license
+
+Report on GitHub Enterprise licensing
+
+### Synopsis
+
+Report on GitHub Enterprise licensing, requires `read:enterprise` and `user:email` scope
+
+```
+report license [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for license
+```
+
+### Options inherited from parent commands
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report](report.md)	 - gh cli extension to generate reports
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/docs/report_repo.md b/docs/report_repo.md
@@ -0,0 +1,41 @@
+## report repo
+
+Report on GitHub repositories
+
+### Synopsis
+
+Report on GitHub repositories, requires `read:enterprise` and/or `read:org` scope
+
+```
+report repo [flags]
+```
+
+### Options
+
+```
+  -h, --help       help for repo
+      --internal   Show internal repositories only
+      --private    Show private repositories only
+      --public     Show public repositories only
+```
+
+### Options inherited from parent commands
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report](report.md)	 - gh cli extension to generate reports
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/docs/report_verified-emails.md b/docs/report_verified-emails.md
@@ -0,0 +1,38 @@
+## report verified-emails
+
+List enterprise/organization members' verified emails
+
+### Synopsis
+
+List enterprise/organization members' verified emails, requires `user:email`, `read:enterprise` and/or `read:org` scope
+
+```
+report verified-emails [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for verified-emails
+```
+
+### Options inherited from parent commands
+
+```
+      --csv string                   Path to CSV file, to save report to file
+  -e, --enterprise read:enterprise   GitHub Enterprise Cloud account (requires read:enterprise scope)
+      --hostname string              GitHub Enterprise Server hostname (default "github.com")
+      --json string                  Path to JSON file, to save report to file
+      --md string                    Path to MD file, to save report to file
+      --no-cache                     Do not cache results for one hour (default "false")
+  -o, --owner read:org               GitHub account organization (requires read:org scope) or user account (requires `n/a` scope)
+  -r, --repo repo                    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")
+```
+
+### SEE ALSO
+
+* [report](report.md)	 - gh cli extension to generate reports
+
+###### Auto generated by spf13/cobra on 25-Mar-2023
diff --git a/go.mod b/go.mod
@@ -20,6 +20,7 @@ require (
 	github.com/cli/safeexec v1.0.1 // indirect
 	github.com/cli/shurcooL-graphql v0.0.3 // indirect
 	github.com/containerd/console v1.0.3 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
 	github.com/gookit/color v1.5.3 // indirect
 	github.com/henvic/httpretty v0.1.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
@@ -30,6 +31,7 @@ require (
 	github.com/mattn/go-runewidth v0.0.14 // indirect
 	github.com/muesli/termenv v0.15.1 // indirect
 	github.com/rivo/uniseg v0.4.4 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/thlib/go-timezone-local v0.0.0-20210907160436-ef149e42d28e // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect

diff --git a/go.sum b/go.sum
@@ -26,6 +26,7 @@ github.com/cli/shurcooL-graphql v0.0.3 h1:CtpPxyGDs136/+ZeyAfUKYmcQBjDlq5aqnrDCW
 github.com/cli/shurcooL-graphql v0.0.3/go.mod h1:tlrLmw/n5Q/+4qSvosT+9/W5zc8ZMjnJeYBxSdb4nWA=
 github.com/containerd/console v1.0.3 h1:lIr7SlA5PxZyMV30bDW0MGbiOPXwc63yRuCP0ARubLw=
 github.com/containerd/console v1.0.3/go.mod h1:7LqA/THxQ86k76b8c/EMSiaJ3h1eZkMkXar0TQ1gf3U=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
 github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -80,6 +81,7 @@ github.com/pterm/pterm v0.12.56/go.mod h1:7rswprkyxYOse1IMh79w42jvReNHxro4z9oHfq
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.4 h1:8TfxU8dW6PdqD27gjM8MVNuicgxIjxpm4K7x4jp8sis=
 github.com/rivo/uniseg v0.4.4/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sergi/go-diff v1.2.0 h1:XU+rvMAioB0UC3q1MFrIQy4Vo5/4VsRDQQXHsEya6xQ=
 github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=

diff --git a/internal/cmd/docs/main.go b/internal/cmd/docs/main.go
@@ -0,0 +1,26 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/spf13/cobra/doc"
+	"github.com/stoe/gh-report/cmd"
+)
+
+func main() {
+	output := "./docs"
+
+	if err := os.RemoveAll(output); err != nil {
+		log.Fatal(fmt.Errorf("failed to remove existing dir: %w", err))
+	}
+
+	if err := os.MkdirAll(output, 0755); err != nil {
+		log.Fatal(fmt.Errorf("failed to mkdir: %w", err))
+	}
+
+	if err := doc.GenMarkdownTree(cmd.RootCmd, output); err != nil {
+		log.Fatal(fmt.Errorf("failed to generate markdown: %w", err))
+	}
+}