Rewrite docs generation (#58)

* Rewrite the docs generation script

* Add examples and update descriptions

* Add `projects list` subcommand

* Generate docs

* Update short descriptions

* Add aliases

* Improve list formatting

* Generate aliases into docs

Author: Mathias Lindholm

cmd/annotate.go

@@ -13,14 +13,13 @@ import (
 )
 
 var annotateCmd = &cobra.Command{
-	Use: "annotate [<input file>] [<app id>]",
-	Example: `speechly annotate -a <app_id> --input input.txt
-speechly annotate -a <app_id> --input input.txt > output.txt
-speechly annotate -a <app_id> --reference-date 2021-01-20 --input input.txt > output.txt
-
-To evaluate already deployed Speechly app, you need a set of evaluation examples that users of your application might say.`,
-	Short: "Create SAL annotations for a list of examples using Speechly.",
-	Args:  cobra.RangeArgs(0, 1),
+	Use:   "annotate",
+	Short: "Create SAL annotations for a list of examples using Speechly",
+	Long:  "To evaluate already deployed Speechly app, you need a set of evaluation examples that users of your application might say.",
+	Example: `speechly annotate input.txt <app_id>
+speechly annotate --app <app_id> --input input.txt > output.txt
+speechly annotate --app <app_id> --reference-date 2021-01-20 --input input.txt > output.txt`,
+	Args: cobra.RangeArgs(0, 1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		appId, err := cmd.Flags().GetString("app")
 		if err != nil {
@@ -108,7 +107,7 @@ To evaluate already deployed Speechly app, you need a set of evaluation examples
 
 func init() {
 	RootCmd.AddCommand(annotateCmd)
-	annotateCmd.Flags().StringP("app", "a", "", "Application to evaluate. Can be given as the first positional argument.")
+	annotateCmd.Flags().StringP("app", "a", "", "Application to evaluate. Can be given as the second positional argument.")
 	annotateCmd.Flags().StringP("input", "i", "", "Evaluation utterances, separated by newline, if not provided, read from stdin. Can be given as the first positional argument.")
 	annotateCmd.Flags().StringP("output", "o", "", "Where to store annotated utterances, if not provided, print to stdout.")
 	annotateCmd.Flags().StringP("reference-date", "r", "", "Reference date in YYYY-MM-DD format, if not provided use current date.")

cmd/common.go

@@ -58,7 +58,7 @@ func waitForAppStatus(cmd *cobra.Command, configClient configv1.ConfigAPIClient,
 		if err != nil {
 			log.Fatalf("Failed to refresh app %s: %s", appId, err)
 		}
-		cmd.Printf("Status:\t%s", app.App.Status)
+		cmd.Printf("Status: %s", app.App.Status)
 		switch app.App.Status {
 		case configv1.App_STATUS_NEW:
 			cmd.Printf(", queued (%d jobs before this)", app.App.QueueSize)

cmd/config.go

@@ -14,9 +14,18 @@ import (
 )
 
 var configCmd = &cobra.Command{
-	Use:     "projects",
-	Aliases: []string{"config"},
+	Use:     "projects [command]",
+	Aliases: []string{"project", "config"},
 	Short:   "Manage API access to Speechly projects",
+	Args:    cobra.NoArgs,
+}
+
+var validName = regexp.MustCompile(`[^A-Za-z0-9]+`)
+
+var configListCmd = &cobra.Command{
+	Use:     "list",
+	Aliases: []string{"ls"},
+	Short:   "List known projects",
 	Run: func(cmd *cobra.Command, args []string) {
 		conf := clients.GetConfig(cmd.Context())
 		cmd.Printf("Settings file used: %s\n", viper.ConfigFileUsed())
@@ -38,12 +47,12 @@ var configCmd = &cobra.Command{
 	},
 }
 
-var validName = regexp.MustCompile(`[^A-Za-z0-9]+`)
-
 var configAddCmd = &cobra.Command{
-	Use:   "add [apikey]",
+	Use:   "add",
 	Short: "Add access to a pre-existing project",
-	Args:  cobra.RangeArgs(0, 1),
+	Example: `speechly projects add <api_token>
+speechly projects add --apikey <api_token>`,
+	Args: cobra.RangeArgs(0, 1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		name, _ := cmd.Flags().GetString("name")
 		if name != "" && validName.MatchString(name) {
@@ -134,8 +143,10 @@ var configAddCmd = &cobra.Command{
 }
 
 var configRemoveCmd = &cobra.Command{
-	Use:   "remove",
-	Short: "Remove access to a project",
+	Use:     "remove",
+	Aliases: []string{"rm"},
+	Short:   "Remove access to a project",
+	Example: `speechly projects remove --name <project_name>`,
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		name, _ := cmd.Flags().GetString("name")
 		if err := ensureContextExists(cmd.Context(), name); err != nil {
@@ -164,8 +175,11 @@ var configRemoveCmd = &cobra.Command{
 }
 
 var configUseCmd = &cobra.Command{
-	Use:   "use",
-	Short: "Select the default project used",
+	Use:     "use",
+	Aliases: []string{"switch"},
+	Short:   "Select the default project used",
+	Example: `speechly projects use
+speechly projects use --name <project_name>`,
 	Run: func(cmd *cobra.Command, args []string) {
 		previousContext := viper.Get("current-context")
 		name, _ := cmd.Flags().GetString("name")
@@ -220,6 +234,8 @@ func ensureContextExists(ctx context.Context, name string) error {
 }
 
 func init() {
+	configCmd.AddCommand(configListCmd)
+
 	configAddCmd.Flags().String("apikey", "", "API token, created in Speechly Dashboard. Can also be given as the sole positional argument.")
 	configAddCmd.Flags().String("name", "", "An unique name for the project. If not given the project name configured in Speechly Dashboard will be used.")
 	configAddCmd.Flags().String("host", "api.speechly.com", "API address")

cmd/convert.go

@@ -27,11 +27,11 @@ func (u ConvertWriter) Write(data []byte) (n int, err error) {
 }
 
 var convertCmd = &cobra.Command{
-	Use: "convert [-l language] <input_file>",
-	Example: `speechly convert my-alexa-skill.json
-speechly convert -l en-US my-alexa-skill.json`,
+	Use:   "convert",
 	Short: "Converts an Alexa Interaction Model in JSON format to a Speechly configuration",
-	Args:  cobra.ExactArgs(1),
+	Example: `speechly convert my-alexa-skill.json
+speechly convert --language en-US my-alexa-skill.json`,
+	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		ctx := cmd.Context()
 		language, _ := cmd.Flags().GetString("language")

cmd/create.go

@@ -13,13 +13,12 @@ import (
 )
 
 var createCmd = &cobra.Command{
-	Use: "create [<application name>]",
-	Example: `speechly create "My App"
-speechly create --name "My App" --output-dir /foo/bar
-`,
+	Use:   "create",
 	Short: "Create a new application in the current project",
 	Long:  "Creates a new application in the current project and a config file in the current working directory.",
-	Args:  cobra.RangeArgs(0, 1),
+	Example: `speechly create "My App"
+speechly create --name "My App" --output-dir /foo/bar`,
+	Args: cobra.RangeArgs(0, 1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		name, _ := cmd.Flags().GetString("name")
 		if name == "" && len(args) == 0 {

cmd/delete.go

@@ -14,9 +14,11 @@ import (
 )
 
 var deleteCmd = &cobra.Command{
-	Use:   "delete [<app_id>]",
+	Use:   "delete",
 	Short: "Delete an existing application",
-	Args:  cobra.RangeArgs(0, 1),
+	Example: `speechly delete <app_id>
+speechly delete --app <app_id> --force`,
+	Args: cobra.RangeArgs(0, 1),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		appId, err := cmd.Flags().GetString("app")
 		if err != nil {

cmd/deploy.go

@@ -27,13 +27,12 @@ func (u DeployWriter) Write(data []byte) (n int, err error) {
 }
 
 var deployCmd = &cobra.Command{
-	Use: "deploy [<app_id>] <directory>",
-	Example: `speechly deploy <app_id> /path/to/config
-speechly deploy -a <app_id> .`,
+	Use:   "deploy",
 	Short: "Send the contents of a local directory to training",
-	Long: `The contents of the directory given as argument is sent to the
-API and validated. Then, a new model is trained and automatically deployed
-as the active model for the application.`,
+	Long:  "The contents of the directory given as argument is sent to the API and validated. Then, a new model is trained and automatically deployed as the active model for the application.",
+	Example: `speechly deploy <app_id> /path/to/config
+speechly deploy --app <app_id> .
+speechly deploy --watch --app <app_id> .`,
 	Args: cobra.RangeArgs(1, 2),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		appId, _ := cmd.Flags().GetString("app")

cmd/describe.go

@@ -10,8 +10,10 @@ import (
 )
 
 var describeCmd = &cobra.Command{
-	Use:     "describe [<app_id>]",
-	Short:   "Print details about an application",
+	Use:   "describe",
+	Short: "Print details about an application",
+	Example: `speechly describe <app_id>
+speechly describe --app <app_id>`,
 	Args:    cobra.RangeArgs(0, 1),
 	PreRunE: checkSoleAppArgument,
 	Run: func(cmd *cobra.Command, args []string) {
@@ -34,16 +36,16 @@ var describeCmd = &cobra.Command{
 		if app.App.DeployedAtTime != nil {
 			deployedAt = app.App.DeployedAtTime.AsTime().String()
 		}
-		cmd.Printf("AppId:\t%s\n", app.App.Id)
-		cmd.Printf("Name:\t%s\n", app.App.Name)
-		cmd.Printf("Lang:\t%s\n", app.App.Language)
+		cmd.Printf("App ID: %s\n", app.App.Id)
+		cmd.Printf("Name: %s\n", app.App.Name)
+		cmd.Printf("Language: %s\n", app.App.Language)
 
 		waitFor := configv1.App_STATUS_UNSPECIFIED
 		if wait {
 			waitFor = configv1.App_STATUS_TRAINED
 		}
 		waitForAppStatus(cmd, configClient, appId, waitFor)
-		cmd.Printf("Deployed At:\t%s\n", deployedAt)
+		cmd.Printf("Deployed at: %s\n", deployedAt)
 	},
 }
 

cmd/download.go

@@ -19,13 +19,12 @@ import (
 )
 
 var downloadCmd = &cobra.Command{
-	Use: "download [<app_id>] <directory> [flags]",
+	Use:   "download",
+	Short: "Download the active configuration or model bundle of the given app",
+	Long:  "Fetches the currently stored configuration or model bundle. This command does not check for validity of the stored configuration, but downloads the latest version.",
 	Example: `speechly download <app_id> /path/to/config
-speechly download -a <app_id> .
-speechly download -a <app_id> . --model tflite`,
-	Short: "Download the active configuration or model bundle of the given app.",
-	Long:  `Fetches the currently stored configuration or model bundle. This command does not check for validity of the stored configuration, but downloads the latest version.`,
-	Args:  cobra.RangeArgs(1, 2),
+speechly download --app <app_id> . --model tflite`,
+	Args: cobra.RangeArgs(1, 2),
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		appId, _ := cmd.Flags().GetString("app")
 		if appId == "" {

cmd/edit.go

@@ -12,6 +12,7 @@ import (
 var editCmd = &cobra.Command{
 	Use:   "edit",
 	Short: "Edit an existing application",
+	Example: `speechly edit --app <app_id> --name <new_name>`,
 	Run: func(cmd *cobra.Command, args []string) {
 		name, _ := cmd.Flags().GetString("name")