From 010d8d5df12235aa945ebfda7a82cdd1c50394c3 Mon Sep 17 00:00:00 2001 From: Georgi Matev Date: Wed, 5 Oct 2022 13:33:47 -0700 Subject: [PATCH] Final Examples indent fix to be consistent in docs and inline usage (#1056) ## Description Previous indent fixed usage but screwed up generated docs. ## Type of change - [ ] :sunflower: Feature - [x] :bug: Bugfix - [ ] :world_map: Documentation - [ ] :robot: Test - [ ] :computer: CI/Deployment - [ ] :hamster: Trivial/Minor ## Issue(s) ## Test Plan - [x] :muscle: Manual - [ ] :zap: Unit test - [ ] :green_heart: E2E --- src/cli/backup/exchange.go | 6 +++--- src/cli/backup/onedrive.go | 10 +++++----- src/cli/cli.go | 16 ++++++++++++++++ src/cli/repo/s3.go | 3 ++- src/cli/restore/exchange.go | 6 +++--- src/cli/restore/onedrive.go | 6 +++--- src/cli/utils/utils.go | 10 ---------- 7 files changed, 32 insertions(+), 25 deletions(-) diff --git a/src/cli/backup/exchange.go b/src/cli/backup/exchange.go index 86cd3c445..a1427accd 100644 --- a/src/cli/backup/exchange.go +++ b/src/cli/backup/exchange.go @@ -105,7 +105,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, exchangeCreateCmd()) c.Use = c.Use + exchangeServiceCommandCreateUseSuffix - c.Example = utils.IndentExamples(exchangeServiceCommandCreateExamples) + c.Example = exchangeServiceCommandCreateExamples // Flags addition ordering should follow the order we want them to appear in help and docs: // More generic (ex: --all) and more frequently used flags take precedence. @@ -129,7 +129,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, exchangeDetailsCmd()) c.Use = c.Use + exchangeServiceCommandDetailsUseSuffix - c.Example = utils.IndentExamples(exchangeServiceCommandDetailsExamples) + c.Example = exchangeServiceCommandDetailsExamples // Flags addition ordering should follow the order we want them to appear in help and docs: // More generic (ex: --all) and more frequently used flags take precedence. @@ -217,7 +217,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, exchangeDeleteCmd()) c.Use = c.Use + exchangeServiceCommandDeleteUseSuffix - c.Example = utils.IndentExamples(exchangeServiceCommandDeleteExamples) + c.Example = exchangeServiceCommandDeleteExamples fs.StringVar(&backupID, "backup", "", "ID of the backup to delete. (required)") cobra.CheckErr(c.MarkFlagRequired("backup")) diff --git a/src/cli/backup/onedrive.go b/src/cli/backup/onedrive.go index 46a87666c..9305aa70e 100644 --- a/src/cli/backup/onedrive.go +++ b/src/cli/backup/onedrive.go @@ -48,11 +48,11 @@ corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --user a # Explore Alice or Bob's files with name containing "Fiscal 22" in folder "Reports" corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com,bob@example.com --file-name "Fiscal 22" --folder "Reports" + --user alice@example.com,bob@example.com --file-name "Fiscal 22" --folder "Reports" # Explore Alice's files created before end of 2015 from a specific backup corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --file-created-before 2015-01-01T00:00:00` + --user alice@example.com --file-created-before 2015-01-01T00:00:00` ) var ( @@ -77,7 +77,7 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, oneDriveCreateCmd()) c.Use = c.Use + oneDriveServiceCommandCreateUseSuffix - c.Example = utils.IndentExamples(oneDriveServiceCommandCreateExamples) + c.Example = oneDriveServiceCommandCreateExamples fs.StringArrayVar(&user, "user", nil, "Backup OneDrive data by user ID; accepts '"+utils.Wildcard+"' to select all users. (required)") @@ -90,7 +90,7 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, oneDriveDetailsCmd()) c.Use = c.Use + oneDriveServiceCommandDetailsUseSuffix - c.Example = utils.IndentExamples(oneDriveServiceCommandDetailsExamples) + c.Example = oneDriveServiceCommandDetailsExamples fs.StringVar(&backupID, "backup", "", "ID of the backup to explore. (required)") cobra.CheckErr(c.MarkFlagRequired("backup")) @@ -131,7 +131,7 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command { c, fs = utils.AddCommand(parent, oneDriveDeleteCmd()) c.Use = c.Use + oneDriveServiceCommandDeleteUseSuffix - c.Example = utils.IndentExamples(oneDriveServiceCommandDeleteExamples) + c.Example = oneDriveServiceCommandDeleteExamples fs.StringVar(&backupID, "backup", "", "ID of the backup to delete. (required)") cobra.CheckErr(c.MarkFlagRequired("backup")) diff --git a/src/cli/cli.go b/src/cli/cli.go index 2602073c0..f109fe469 100644 --- a/src/cli/cli.go +++ b/src/cli/cli.go @@ -3,6 +3,8 @@ package cli import ( "context" "os" + "regexp" + "strings" "github.com/spf13/cobra" @@ -68,6 +70,8 @@ func BuildCommandTree(cmd *cobra.Command) { print.AddOutputFlag(cmd) options.AddGlobalOperationFlags(cmd) + cmd.SetUsageTemplate(indentExamplesTemplate(corsoCmd.UsageTemplate())) + cmd.CompletionOptions.DisableDefaultCmd = true repo.AddCommands(cmd) @@ -96,3 +100,15 @@ func Handle() { os.Exit(1) } } + +// Adjust the default usage template which does not properly indent examples +func indentExamplesTemplate(template string) string { + cobra.AddTemplateFunc("indent", func(spaces int, v string) string { + pad := strings.Repeat(" ", spaces) + return pad + strings.Replace(v, "\n", "\n"+pad, -1) + }) + + e := regexp.MustCompile(`{{\.Example}}`) + + return e.ReplaceAllString(template, "{{.Example | indent 2}}") +} diff --git a/src/cli/repo/s3.go b/src/cli/repo/s3.go index 6c06d1b16..ce50352e0 100644 --- a/src/cli/repo/s3.go +++ b/src/cli/repo/s3.go @@ -38,6 +38,7 @@ func addS3Commands(parent *cobra.Command) *cobra.Command { } c.Use = c.Use + s3ProviderCommandUseSuffix + c.SetUsageTemplate(parent.UsageTemplate()) // Flags addition ordering should follow the order we want them to appear in help and docs: // More generic (ex: --all) and more frequently used flags take precedence. @@ -90,7 +91,7 @@ func s3InitCmd() *cobra.Command { Long: `Bootstraps a new S3 repository and connects it to your m356 account.`, RunE: initS3Cmd, Args: cobra.NoArgs, - Example: utils.IndentExamples(s3ProviderCommandInitExamples), + Example: s3ProviderCommandInitExamples, } } diff --git a/src/cli/restore/exchange.go b/src/cli/restore/exchange.go index 292184142..0bf3024e3 100644 --- a/src/cli/restore/exchange.go +++ b/src/cli/restore/exchange.go @@ -147,11 +147,11 @@ corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --email 98765ab # Restore Alice's emails with subject containing "Hello world" in "Inbox" from a specific backup corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --email-subject "Hello world" --email-folder Inbox + --user alice@example.com --email-subject "Hello world" --email-folder Inbox # Restore Bobs's entire calendar from a specific backup corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user bob@example.com --event-calendar Calendar + --user bob@example.com --event-calendar Calendar # Restore contact with ID abdef0101 from a specific backup corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --contact abdef0101` @@ -164,7 +164,7 @@ func exchangeRestoreCmd() *cobra.Command { Short: "Restore M365 Exchange service data", RunE: restoreExchangeCmd, Args: cobra.NoArgs, - Example: utils.IndentExamples(exchangeServiceCommandRestoreExamples), + Example: exchangeServiceCommandRestoreExamples, } } diff --git a/src/cli/restore/onedrive.go b/src/cli/restore/onedrive.go index bd6b69d0b..2a26c0abb 100644 --- a/src/cli/restore/onedrive.go +++ b/src/cli/restore/onedrive.go @@ -97,11 +97,11 @@ corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abc # Restore Alice's file named "FY2021 Planning.xlsx in "Documents/Finance Reports" from a specific backup corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports" + --user alice@example.com --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports" # Restore all files from Bob's folder that were created before 2020 when captured in a specific backup corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd - --user bob@example.com --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00` + --user bob@example.com --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00` ) // `corso restore onedrive [...]` @@ -111,7 +111,7 @@ func oneDriveRestoreCmd() *cobra.Command { Short: "Restore M365 OneDrive service data", RunE: restoreOneDriveCmd, Args: cobra.NoArgs, - Example: utils.IndentExamples(oneDriveServiceCommandRestoreExamples), + Example: oneDriveServiceCommandRestoreExamples, } } diff --git a/src/cli/utils/utils.go b/src/cli/utils/utils.go index 520c34ada..74b43cc57 100644 --- a/src/cli/utils/utils.go +++ b/src/cli/utils/utils.go @@ -4,7 +4,6 @@ import ( "context" "errors" "fmt" - "regexp" "github.com/spf13/cobra" "github.com/spf13/pflag" @@ -58,12 +57,3 @@ func AddCommand(parent, c *cobra.Command) (*cobra.Command, *pflag.FlagSet) { return c, c.Flags() } - -// Takes in a multi-line string and returns it indented by 2 spaces. -// This is only to be used with Examples strings which the default usage -// template does not properly indent to match other sections -func IndentExamples(examples string) string { - e := regexp.MustCompile(`(?m)^`) - - return e.ReplaceAllString(examples, " ") -}