documentation for commands (#81)

* documentation for commands
* upgraded Cobra version

Author: az-smartling

Makefile

@@ -61,6 +61,9 @@ _pkg-init:
 %:
 	GOOS=$(basename $@) go build -o bin/smartling.$@
 
+docs:
+	go run ./main.go docs
+
 tidy:
 	go mod tidy
 
@@ -90,3 +93,4 @@ test_integration:
 	go test ./tests/cmd/files/delete/...
 	go test ./tests/cmd/projects/...
 	go test ./tests/cmd/init/...
+

cmd/cmd_root.go

@@ -30,7 +30,7 @@ func NewRootCmd() *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:     "smartling-cli",
 		Short:   "Manage translation files using Smartling CLI.",
-		Version: "2.4.1",
+		Version: "2.5",
 		Long: `Manage translation files using Smartling CLI.
                 Complete documentation is available at https://www.smartling.com`,
 		PersistentPreRun: func(cmd *cobra.Command, _ []string) {

cmd/docs/cmd_docs.go

@@ -0,0 +1,29 @@
+package docs
+
+import (
+	"fmt"
+
+	"github.com/Smartling/smartling-cli/services/helpers/rlog"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+// NewDocsCmd creates a new command to generate docs.
+func NewDocsCmd() *cobra.Command {
+	docsCmd := &cobra.Command{
+		Use:    "docs",
+		Short:  "Generate markdown docs for CLI commands",
+		Hidden: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			err := doc.GenMarkdownTree(cmd.Root(), "./docs")
+			if err != nil {
+				return fmt.Errorf("failed to generate docs: %v", err)
+			}
+			rlog.Infof("markdown docs generated in ./docs/")
+			return nil
+		},
+	}
+
+	return docsCmd
+}

cmd/files/cmd_files.go

@@ -18,6 +18,12 @@ func NewFilesCmd() *cobra.Command {
 		Aliases: []string{"f"},
 		Short:   "Used to access various files sub-commands.",
 		Long:    `Used to access various files sub-commands.`,
+		Example: `
+# Check file status across locales
+
+smartling-cli files status
+
+`,
 		Run: func(cmd *cobra.Command, args []string) {
 			if len(args) == 0 && cmd.Flags().NFlag() == 0 {
 				if err := cmd.Help(); err != nil {

cmd/files/delete/cmd_delete.go

@@ -21,7 +21,7 @@ func NewDeleteCmd(initializer files.SrvInitializer) *cobra.Command {
 
 Removes files from project according to specified pattern.
 
-<uri> ` + help.GlobPattern + `
+` + "`<uri>` " + help.GlobPattern + ` 
 
 If special value of "-" is specified as <uri>, then program will expect
 to read files list from stdin:

cmd/files/list/cmd_list.go

@@ -42,7 +42,7 @@ Following variables are available:
   > .LastUploaded — timestamp when file was last uploaded;
   > .HasInstructions — true/false if file has translation instructions;
 
-<uri> ` + help.GlobPattern + `
+` + "`<uri>` " + help.GlobPattern + `
 
 
 Available options:
@@ -55,6 +55,11 @@ Available options:
   --format <format>
     Override default listing format.
 ` + help.AuthenticationOptions,
+		Example: `
+# List project files
+
+smartling-cli files list
+`,
 		Run: func(_ *cobra.Command, args []string) {
 			var uri string
 			if len(args) > 0 {

cmd/files/pull/cmd_pull.go

@@ -40,7 +40,7 @@ to read files list from stdin:
 
   cat files.txt | smartling-cli files pull -
 
-<uri> ` + help.GlobPattern + `
+` + "`<uri>` " + help.GlobPattern + ` 
 
 If --locale flag is not specified, all available locales are downloaded. To
 see available locales, use "status" command.
@@ -85,6 +85,11 @@ Available options:
                characters transformed;
     > contextMatchingInstrumented — to use with Chrome Context Capture;
 ` + help.AuthenticationOptions,
+		Example: `
+# Download translated files
+
+smartling-cli files pull "**/*.json" --locale fr-FR --locale de-DE
+`,
 		Run: func(_ *cobra.Command, args []string) {
 			if len(args) > 0 {
 				uri = args[0]

cmd/files/push/cmd_push.go

@@ -55,9 +55,39 @@ File type will be deduced from file extension. If file extension is unknown,
 type should be specified manually by using --type option. That option also
 can be used to override detected file type.
 
-<file> ` + help.GlobPattern + `
+` + "`<file>` " + help.GlobPattern + ` 
 
 ` + help.AuthenticationOptions,
+		Example: `
+# Upload files to a translation job
+
+smartling-cli files push my-file.txt --job "Website Update" --authorize
+
+# Upload multiple files with pattern matching
+
+smartling-cli files push "src/**/*.json" --job "App Localization"
+
+# Manual branch naming
+
+smartling-cli files push "**/*.txt" --branch "feature-branch"
+
+# Automatic Git branch detection
+
+smartling-cli files push "**/*.txt" --branch "@auto"
+
+# All JSON files in subdirectories
+
+smartling-cli files push "**/*.json"
+
+# Specific file types
+
+smartling-cli files push "**/*.{json,xml,properties}"
+
+# Files matching naming convention
+
+smartling-cli files push "**/messages_*.properties"
+
+`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 			var (

cmd/files/status/cmd_status.go

@@ -50,7 +50,7 @@ Following variables are available:
   > .FileURI — full file URI in Smartling system;
   > .Locale — locale ID for translated file and empty for source file;
 
-<uri> ` + help.GlobPattern + `
+` + "`<uri>` " + help.GlobPattern + ` 
 
 
 Available options:

cmd/init/cmd_init.go

@@ -36,7 +36,7 @@ config values prior dialog:
   smartling-cli init --user=your_user_id
 
 Also, --dry-run option can be used to just look at resulting config without
-overwritting anything:
+overwriting anything:
 
   smartling-cli init --dry-run
 
@@ -57,6 +57,18 @@ Default config values can be passed via following options:` +
 			help.AuthenticationOptions + `
   -p --project <project>
     Specify default project.`,
+		Example: `
+# Create a configuration file with your Smartling API credentials:
+# This creates a smartling.yml file in your current directory with your project settings.
+# Note: Running init again will overwrite the existing configuration file.
+
+smartling-cli init
+
+# Dry run of init command without overwriting the existing configuration file.
+
+smartling-cli init --dry-run
+
+`,
 		Run: func(_ *cobra.Command, _ []string) {
 			s, err := srvInitializer.InitSrv()
 			if err != nil {