From fcf9e9f38f828d8935d55f1a3fdd41afeb6be042 Mon Sep 17 00:00:00 2001 From: BekahHW <34313413+BekahHW@users.noreply.github.com> Date: Tue, 10 Sep 2024 14:57:46 -0400 Subject: [PATCH] chore: update docs for generate and codeowners (#163) * Clarify short description * Create more informative flag descriptions * Add Example section * Fix linebreaks * Add long description to generate * Revise short description for generate * Add generating codeowners to long description * Add generate docs * Change saucedctl to codeowners * Change all saucectl to codeowners to reflect changes * Remove POC message and extra indents * Remove duplicated line * Remove command repetition * Add back tick back in * Adds configuration documentation to explain the sauced.yaml file * Remove indentation from examples * Use correct path for default --- README.md | 2 +- cmd/generate/codeowners/codeowners.go | 36 ++++++++++++++++----- cmd/generate/generate.go | 6 ++-- cmd/root/root.go | 4 +-- docs/pizza.md | 6 ++-- docs/pizza_completion.md | 2 +- docs/pizza_completion_bash.md | 2 +- docs/pizza_completion_fish.md | 2 +- docs/pizza_completion_powershell.md | 2 +- docs/pizza_completion_zsh.md | 2 +- docs/pizza_generate.md | 13 +++++--- docs/pizza_generate_codeowners.md | 39 ++++++++++++++++------- docs/pizza_insights.md | 2 +- docs/pizza_insights_contributors.md | 2 +- docs/pizza_insights_repositories.md | 2 +- docs/pizza_insights_user-contributions.md | 2 +- docs/pizza_login.md | 2 +- docs/pizza_version.md | 2 +- 18 files changed, 83 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 27f4d3e..9f4b80c 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,7 @@ Flags: Global Flags: --beta Shorthand for using the beta OpenSauced API endpoint ("https://beta.api.opensauced.pizza"). Supersedes the '--endpoint' flag - -c, --config string The saucectl config (default "~/.sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -e, --endpoint string The API endpoint to send requests to (default "https://api.opensauced.pizza") -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") diff --git a/cmd/generate/codeowners/codeowners.go b/cmd/generate/codeowners/codeowners.go index 8f174dd..20491dd 100644 --- a/cmd/generate/codeowners/codeowners.go +++ b/cmd/generate/codeowners/codeowners.go @@ -46,21 +46,41 @@ type Options struct { config *config.Spec } -const codeownersLongDesc string = `WARNING: Proof of concept feature. +const codeownersLongDesc string = `Generates a CODEOWNERS file for a given git repository. The generated file specifies up to 3 owners for EVERY file in the git tree based on the number of lines touched in that specific file over the specified range of time. -Generates a CODEOWNERS file for a given git repository. This uses a .sauced.yaml -configuration to attribute emails with given entities. +Configuration: +The command requires a .sauced.yaml file for accurate attribution. This file maps +commit email addresses to GitHub usernames. The command looks for this file in two locations: -The generated file specifies up to 3 owners for EVERY file in the git tree based on the -number of lines touched in that specific file over the specified range of time.` +1. In the root of the specified repository path +2. In the user's home directory (~/.sauced.yaml) if not found in the repository + +If you run the command on a specific path, it will first look for .sauced.yaml in that +path. If not found, it will fall back to ~/.sauced.yaml.` func NewCodeownersCommand() *cobra.Command { opts := &Options{} cmd := &cobra.Command{ Use: "codeowners path/to/repo [flags]", - Short: "Generates a CODEOWNERS file for a given repository using a \".sauced.yaml\" config", + Short: "Generate a CODEOWNERS file for a GitHub repository using a \"~/.sauced.yaml\" config", Long: codeownersLongDesc, + Example: ` +# Generate CODEOWNERS file for the current directory +pizza generate codeowners . + +# Generate CODEOWNERS file for a specific repository +pizza generate codeowners /path/to/your/repo + +# Generate CODEOWNERS file analyzing the last 180 days +pizza generate codeowners . --range 180 + +# Generate an OWNERS style file instead of CODEOWNERS +pizza generate codeowners . --owners-style-file + +# Specify a custom location for the .sauced.yaml file +pizza generate codeowners . --config /path/to/.sauced.yaml + `, Args: func(_ *cobra.Command, args []string) error { if len(args) != 1 { return errors.New("you must provide exactly one argument: the path to the repository") @@ -119,8 +139,8 @@ func NewCodeownersCommand() *cobra.Command { }, } - cmd.PersistentFlags().IntP("range", "r", 90, "The number of days to lookback") - cmd.PersistentFlags().Bool("owners-style-file", false, "Whether to generate an agnostic OWNERS style file.") + cmd.PersistentFlags().IntP("range", "r", 90, "The number of days to analyze commit history (default 90)") + cmd.PersistentFlags().Bool("owners-style-file", false, "Generate an agnostic OWNERS style file instead of CODEOWNERS.") return cmd } diff --git a/cmd/generate/generate.go b/cmd/generate/generate.go index b3ff321..aa2c800 100644 --- a/cmd/generate/generate.go +++ b/cmd/generate/generate.go @@ -8,14 +8,12 @@ import ( "github.com/open-sauced/pizza-cli/cmd/generate/codeowners" ) -const generateLongDesc string = `WARNING: Proof of concept feature. - -XXX` +const generateLongDesc string = `The 'generate' command provides tools to automate the creation of important project documentation and derive insights from your codebase.` func NewGenerateCommand() *cobra.Command { cmd := &cobra.Command{ Use: "generate [subcommand] [flags]", - Short: "Generates something", + Short: "Generates documentation and insights from your codebase", Long: generateLongDesc, Args: func(_ *cobra.Command, args []string) error { if len(args) != 1 { diff --git a/cmd/root/root.go b/cmd/root/root.go index 9dbbc45..7b35e4a 100644 --- a/cmd/root/root.go +++ b/cmd/root/root.go @@ -19,7 +19,7 @@ func NewRootCommand() (*cobra.Command, error) { cmd := &cobra.Command{ Use: "pizza [flags]", Short: "OpenSauced CLI", - Long: "A command line utility for insights, metrics, and all things OpenSauced", + Long: "A command line utility for insights, metrics, and generating CODEOWNERS documentation for your open source projects", RunE: run, Args: func(cmd *cobra.Command, _ []string) error { betaFlag := cmd.Flags().Lookup(constants.FlagNameBeta) @@ -36,7 +36,7 @@ func NewRootCommand() (*cobra.Command, error) { cmd.PersistentFlags().StringP(constants.FlagNameEndpoint, "e", constants.EndpointProd, "The API endpoint to send requests to") cmd.PersistentFlags().Bool(constants.FlagNameBeta, false, fmt.Sprintf("Shorthand for using the beta OpenSauced API endpoint (\"%s\"). Supersedes the '--%s' flag", constants.EndpointBeta, constants.FlagNameEndpoint)) cmd.PersistentFlags().Bool(constants.FlagNameTelemetry, false, "Disable sending telemetry data to OpenSauced") - cmd.PersistentFlags().StringP("config", "c", ".sauced.yaml", "The saucectl config") + cmd.PersistentFlags().StringP("config", "c", "~/.sauced.yaml", "The codeowners config") cmd.PersistentFlags().StringP("log-level", "l", "info", "The logging level. Options: error, warn, info, debug") cmd.PersistentFlags().Bool("tty-disable", false, "Disable log stylization. Suitable for CI/CD and automation") diff --git a/docs/pizza.md b/docs/pizza.md index d265d6f..16f72ba 100644 --- a/docs/pizza.md +++ b/docs/pizza.md @@ -4,7 +4,7 @@ OpenSauced CLI ### Synopsis -A command line utility for insights, metrics, and all things OpenSauced +A command line utility for insights, metrics, and generating CODEOWNERS documentation for your open source projects ``` pizza [flags] @@ -13,7 +13,7 @@ pizza [flags] ### Options ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -h, --help help for pizza -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") @@ -23,7 +23,7 @@ pizza [flags] ### SEE ALSO * [pizza completion](pizza_completion.md) - Generate the autocompletion script for the specified shell -* [pizza generate](pizza_generate.md) - Generates something +* [pizza generate](pizza_generate.md) - Generates documentation and insights from your codebase * [pizza insights](pizza_insights.md) - Gather insights about git contributors, repositories, users and pull requests * [pizza login](pizza_login.md) - Log into the CLI via GitHub * [pizza version](pizza_version.md) - Displays the build version of the CLI diff --git a/docs/pizza_completion.md b/docs/pizza_completion.md index eb0665e..242f5e5 100644 --- a/docs/pizza_completion.md +++ b/docs/pizza_completion.md @@ -17,7 +17,7 @@ See each sub-command's help for details on how to use the generated script. ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_completion_bash.md b/docs/pizza_completion_bash.md index 6870d8c..cabb559 100644 --- a/docs/pizza_completion_bash.md +++ b/docs/pizza_completion_bash.md @@ -40,7 +40,7 @@ pizza completion bash ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_completion_fish.md b/docs/pizza_completion_fish.md index 5aa9ed9..d58cc2b 100644 --- a/docs/pizza_completion_fish.md +++ b/docs/pizza_completion_fish.md @@ -31,7 +31,7 @@ pizza completion fish [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_completion_powershell.md b/docs/pizza_completion_powershell.md index 4514dd6..2256317 100644 --- a/docs/pizza_completion_powershell.md +++ b/docs/pizza_completion_powershell.md @@ -28,7 +28,7 @@ pizza completion powershell [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_completion_zsh.md b/docs/pizza_completion_zsh.md index 5910a5b..0b8d87e 100644 --- a/docs/pizza_completion_zsh.md +++ b/docs/pizza_completion_zsh.md @@ -42,7 +42,7 @@ pizza completion zsh [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_generate.md b/docs/pizza_generate.md index 86eb183..74f6ae5 100644 --- a/docs/pizza_generate.md +++ b/docs/pizza_generate.md @@ -1,12 +1,15 @@ ## pizza generate -Generates something +Generates documentation and insights from your codebase ### Synopsis -WARNING: Proof of concept feature. +The 'generate' command provides tools to automate the creation of important project documentation and derive insights from your codebase. -XXX +Currently, it supports generating CODEOWNERS files. + +Available subcommands: + - codeowners: Generate a more granular GitHub-style CODEOWNERS file based on git history. ``` pizza generate [subcommand] [flags] @@ -21,7 +24,7 @@ pizza generate [subcommand] [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation @@ -30,5 +33,5 @@ pizza generate [subcommand] [flags] ### SEE ALSO * [pizza](pizza.md) - OpenSauced CLI -* [pizza generate codeowners](pizza_generate_codeowners.md) - Generates a CODEOWNERS file for a given repository using a ".sauced.yaml" config +* [pizza generate codeowners](pizza_generate_codeowners.md) - Generate a CODEOWNERS file for a GitHub repository using a "~/.sauced.yaml" config diff --git a/docs/pizza_generate_codeowners.md b/docs/pizza_generate_codeowners.md index 3752264..8b476dc 100644 --- a/docs/pizza_generate_codeowners.md +++ b/docs/pizza_generate_codeowners.md @@ -1,33 +1,50 @@ ## pizza generate codeowners -Generates a CODEOWNERS file for a given repository using a ".sauced.yaml" config +Generate a CODEOWNERS file for a GitHub repository using a "~/.sauced.yaml" config ### Synopsis -WARNING: Proof of concept feature. +Generates a CODEOWNERS file for a given git repository. This uses a ~/.sauced.yaml configuration to attribute emails with given entities. -Generates a CODEOWNERS file for a given git repository. This uses a .sauced.yaml -configuration to attribute emails with given entities. - -The generated file specifies up to 3 owners for EVERY file in the git tree based on the -number of lines touched in that specific file over the specified range of time. +The generated file specifies up to 3 owners for EVERY file in the git tree based on the number of lines touched in that specific file over the specified range of time. ``` pizza generate codeowners path/to/repo [flags] ``` +### Examples + +``` + + # Generate CODEOWNERS file for the current directory + pizza generate codeowners . + + # Generate CODEOWNERS file for a specific repository + pizza generate codeowners /path/to/your/repo + + # Generate CODEOWNERS file analyzing the last 180 days + pizza generate codeowners . --range 180 + + # Generate an OWNERS style file instead of CODEOWNERS + pizza generate codeowners . --owners-style-file + + # Specify a custom location for the .sauced.yaml file + pizza generate codeowners . --config /path/to/.sauced.yaml + +``` + ### Options ``` -h, --help help for codeowners - --owners-style-file Whether to generate an agnostic OWNERS style file. - -r, --range int The number of days to lookback (default 90) + --owners-style-file Generate an agnostic OWNERS style file instead of CODEOWNERS. + -r, --range int The number of days to analyze commit history (default 90) (default 90) ``` ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation @@ -35,5 +52,5 @@ pizza generate codeowners path/to/repo [flags] ### SEE ALSO -* [pizza generate](pizza_generate.md) - Generates something +* [pizza generate](pizza_generate.md) - Generates documentation and insights from your codebase diff --git a/docs/pizza_insights.md b/docs/pizza_insights.md index f841a91..b71a3a7 100644 --- a/docs/pizza_insights.md +++ b/docs/pizza_insights.md @@ -20,7 +20,7 @@ pizza insights [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_insights_contributors.md b/docs/pizza_insights_contributors.md index 0e12b79..499ed2e 100644 --- a/docs/pizza_insights_contributors.md +++ b/docs/pizza_insights_contributors.md @@ -21,7 +21,7 @@ pizza insights contributors url... [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") -o, --output string The formatting for command output. One of: (table, yaml, csv, json) (default "table") diff --git a/docs/pizza_insights_repositories.md b/docs/pizza_insights_repositories.md index dd297b5..b46c2a1 100644 --- a/docs/pizza_insights_repositories.md +++ b/docs/pizza_insights_repositories.md @@ -21,7 +21,7 @@ pizza insights repositories url... [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") -o, --output string The formatting for command output. One of: (table, yaml, csv, json) (default "table") diff --git a/docs/pizza_insights_user-contributions.md b/docs/pizza_insights_user-contributions.md index 26fd69d..d59b71e 100644 --- a/docs/pizza_insights_user-contributions.md +++ b/docs/pizza_insights_user-contributions.md @@ -23,7 +23,7 @@ pizza insights user-contributions url... [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") -o, --output string The formatting for command output. One of: (table, yaml, csv, json) (default "table") diff --git a/docs/pizza_login.md b/docs/pizza_login.md index a3d9a2e..8859efd 100644 --- a/docs/pizza_login.md +++ b/docs/pizza_login.md @@ -22,7 +22,7 @@ pizza login [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation diff --git a/docs/pizza_version.md b/docs/pizza_version.md index db9900e..a19188b 100644 --- a/docs/pizza_version.md +++ b/docs/pizza_version.md @@ -15,7 +15,7 @@ pizza version [flags] ### Options inherited from parent commands ``` - -c, --config string The saucectl config (default ".sauced.yaml") + -c, --config string The codeowners config (default ".sauced.yaml") --disable-telemetry Disable sending telemetry data to OpenSauced -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") --tty-disable Disable log stylization. Suitable for CI/CD and automation