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

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

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
 }

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 {

cmd/root/root.go

@@ -19,7 +19,7 @@ func NewRootCommand() (*cobra.Command, error) {
 	cmd := &cobra.Command{
 		Use:   "pizza <command> <subcommand> [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")
 

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 <command> <subcommand> [flags]
@@ -13,7 +13,7 @@ pizza <command> <subcommand> [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 <command> <subcommand> [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

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

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

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

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

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

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
 

docs/pizza_generate_codeowners.md

@@ -1,39 +1,56 @@
 ## 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
 ```
 
 ### SEE ALSO
 
-* [pizza generate](pizza_generate.md)	 - Generates something
+* [pizza generate](pizza_generate.md)	 - Generates documentation and insights from your codebase
 

docs/pizza_insights.md

@@ -20,7 +20,7 @@ pizza insights <command> [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

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

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

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

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

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