Merge pull request #26 from lixiaojun629/develop

update readme & gendoc

.gitattributes

@@ -0,0 +1 @@
+docs export-ignore

README.md

@@ -1,56 +1,75 @@
-##  <u>ucloud-cli 
+##  UCloud CLI 
 
-- website: https://www.ucloud.cn/
+![](./docs/_static/ucloud_cli_demo.gif)
 
-![](http://cli-ucloud-logo.sg.ufileos.com/ucloud.png)
+The UCloud CLI provides a unified command line interface to UCloud services. It works on Golang SDK based on UCloud OpenAPI and supports Linux, macOS and Windows. 
 
-The ucloud-cli provides a unified command line interface to manage Ucloud services. It works through Golang SDK based on UCloud OpenAPI and support Linux, macOS, and Windows. 
+## Installing ucloud-cli
 
-## Installation
+**Using Homebrew(Preferred)**
 
-The easiest way to install ucloud-cli is to use home-brew for Linux and macOS users. This will install the package as well as all dependencies.
+The [Homebrew](https://docs.brew.sh/Installation) package manager may be used on macOS, Linux and Windows Subsystem for Linux (WSL).
+It could install ucloud-cli and its dependencies automatically by running command below.
 
 ```
 $ brew install ucloud
 ```
 
-If you have the ucloud-cli installed and want to upgrade to the latest version you can run:
+If you have installed ucloud-cli already and want to upgrade to the latest version, just run:
 
 ```
 $ brew upgrade ucloud
 ```
 
-**Note**
-
-If you come across error during the installation via home-brew, you may update the management package first.
+If you come across some errors during the installation via homebrew, please update the homebrew first and try again.
 
 ```
 $ brew update
 ```
 
-**Build from the source code**
+If the error is still unresolved, try the following command for help.
+
+```
+$ brew doctor
+```
+
+**Building from source**
 
-For windows users, suggest build from the source code which require install Golang first. This also works for Linux and macOS.
+If you have installed git and golang on your platform, you can fetch the source code of ucloud cli from github and complie it by yourself.
 
 ```
-$ mkdir -p $GOPATH/src/github.com/ucloud
-$ cd $GOPATH/src/github.com/ucloud
 $ git clone https://github.com/ucloud/ucloud-cli.git
 $ cd ucloud-cli
 $ make install
 ```
 
-## Command Completion
+**Downloading binary release**
+
+Vist the [Releases page](https://github.com/ucloud/ucloud-cli/releases) of ucloud cli, and find the appropriate archive for your operating system and architecture.
+Download the archive , check the shasum256 hashcode and extract it to your $PATH
+
+For example
+```
+curl -OL https://github.com/ucloud/ucloud-cli/releases/download/0.1.14/ucloud-cli-macosx-0.1.14-amd64.tgz
+echo "6953232b20f3474973cf234218097006a2e0d1d049c115da6c0e09c103762d4d *ucloud-cli-macosx-0.1.14-amd64.tgz" | shasum -c
+tar zxf ucloud-cli-macosx-0.1.14-amd64.tgz -C /usr/local/bin/
+```
+
+## Enabling Shell Auto-Completion
 
-The ucloud-cli include command completion feature and need configure it manually. 
+UCloud CLI also has auto-completion support. It can be set up so that if you partially type a command and then press TAB, the rest of the command is automatically filled in.
 
-**Bash shell** Add following scripts to  ~/.bash_profile or ~/.bashrc 
+**Bash shell** 
+
+Add following scripts to  ~/.bash_profile or ~/.bashrc 
 
 ```
 complete -C $(which ucloud) ucloud
 ```
 
-**Zsh shell** please add following scripts to ~/.zshrc 
+**Zsh shell** 
+
+Add following scripts to ~/.zshrc 
 
 ```
 autoload -U +X bashcompinit && bashcompinit
@@ -70,54 +89,48 @@ compctl -K _ucloud ucloud
 ```
 
 
-## Getting Started
+## Setup configuration
 
-Run the command to get started and configure ucloud-cli follow the steps. The public & private keys will be saved automatically and locally to directory ~/.ucloud.
+Run the command below to get started and configure ucloud-cli. The private key and public key will be saved automatically and locally to directory ~/.ucloud.
 You can delete the directory whenever you want.
 
 ```
 $ ucloud init
 ```
 
-To reset the configurations, run the command:
+To reset the configurations, run:
 
 ```
 $ ucloud config
 ```
 
-To learn the usage and flags, run the command:
+For more information, run:
 
 ```
-$ ucloud help
+$ ucloud config --help
 ```
 
-## Example
+## For example
 
-Taking create uhost in Nigeria (region: air-nigeria) and bind a public IP as an example, then configure GlobalSSH to accelerate the SSH efficiency beyond China mainland.
+I want to create a uhost in Nigeria (region: air-nigeria) and bind a public IP, and then configure GlobalSSH to accelerate efficiency of SSH service beyond China mainland.
 
-First to create an uhost instance:
+Firstly, create an uhost instance:
 
 ```
 $ ucloud uhost create --cpu 1 --memory 1 --password **** --image-id uimage-fya3qr
 
-UHost:[uhost-tr1e] created successfully!
+uhost[uhost-zbuxxxx] is initializing...done
 ```
 
 *Note* 
 
-Run follow command to get details regarding the parameters to create new uhost instance.
+Run command below to get details about the parameters of creating new uhost instance.
 
 ```
 $ ucloud uhost create --help
 ```
 
-And suggest run the command to get the image-id first.
-
-```
-$ ucloud image list
-```
-
-Secondly, we're going to allocate an EIP and bind to the instance created above.
+Secondly, we're going to allocate an EIP and then bind it to the uhost created above.
 
 ```
 $ ucloud eip allocate --line International --bandwidth 1

cmd/root.go

@@ -16,6 +16,7 @@ package cmd
 
 import (
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/spf13/cobra"
@@ -32,10 +33,10 @@ var global = base.Global
 func NewCmdRoot() *cobra.Command {
 	out := base.Cxt.GetWriter()
 	cmd := &cobra.Command{
-		Use:                    "ucloud",
-		Short:                  "UCloud CLI v" + base.Version,
-		Long:                   `UCloud CLI - manage UCloud resources and developer workflow`,
-		BashCompletionFunction: "__ucloud_init_completion",
+		Use:               "ucloud",
+		Short:             "UCloud CLI v" + base.Version,
+		Long:              `UCloud CLI - manage UCloud resources and developer workflow`,
+		DisableAutoGenTag: true,
 		Run: func(cmd *cobra.Command, args []string) {
 			if global.Version {
 				base.Cxt.Printf("ucloud cli %s\n", base.Version)
@@ -59,7 +60,7 @@ func NewCmdRoot() *cobra.Command {
 	cmd.Flags().BoolVar(&global.Signup, "signup", false, "Launch UCloud sign up page in browser")
 
 	cmd.AddCommand(NewCmdInit())
-	cmd.AddCommand(NewCmdDoc())
+	cmd.AddCommand(NewCmdDoc(out))
 	cmd.AddCommand(NewCmdConfig())
 	cmd.AddCommand(NewCmdRegion())
 	cmd.AddCommand(NewCmdProject())
@@ -87,28 +88,49 @@ func NewCmdRoot() *cobra.Command {
 }
 
 //NewCmdDoc ucloud doc
-func NewCmdDoc() *cobra.Command {
-	var dir string
+func NewCmdDoc(out io.Writer) *cobra.Command {
+	var dir, format string
 	cmd := &cobra.Command{
-		Use:   "doc",
+		Use:   "gendoc",
 		Short: "Generate documents for all commands",
-		Long:  "Generate documents for all commands",
+		Long:  "Generate documents for all commands. Support markdown, rst and douku",
 		Run: func(c *cobra.Command, args []string) {
 			rootCmd := NewCmdRoot()
-			emptyStr := func(s string) string { return "" }
-			linkHandler := func(name, ref string) string {
-				return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
-			}
-			err := doc.GenReSTTreeCustom(rootCmd, dir, emptyStr, linkHandler)
-			if err != nil {
-				log.Fatal(err)
+			switch format {
+			case "rst":
+				emptyStr := func(s string) string { return "" }
+				linkHandler := func(name, ref string) string {
+					return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
+				}
+				err := doc.GenReSTTreeCustom(rootCmd, dir, emptyStr, linkHandler)
+				if err != nil {
+					log.Fatal(err)
+				}
+
+			case "markdown":
+				err := doc.GenMarkdownTree(rootCmd, dir)
+				if err != nil {
+					log.Fatal(err)
+				}
+			case "douku":
+				err := doc.GenDoukuTree(rootCmd, dir, "software/cli/cmd/")
+				if err != nil {
+					log.Fatal(err)
+				}
+			default:
+				fmt.Fprintf(out, "format %s is not supported\n", format)
 			}
 		},
 	}
-	cmd.Flags().StringVar(&dir, "dir", "", "Required. the directory where documents of commands are stored")
+
+	cmd.Flags().StringVar(&dir, "dir", "", "Required. The directory where documents of commands are stored")
+	cmd.Flags().StringVar(&format, "format", "douku", "Required. Format of the doucments. Accept values: markdown, rst and douku")
+
+	cmd.Flags().SetFlagValues("format", "douku", "markdown", "rst")
 	cmd.Flags().SetFlagValuesFunc("dir", func() []string {
 		return base.GetFileList("")
 	})
+
 	cmd.MarkFlagRequired("dir")
 
 	return cmd

cmd/uhost.go

@@ -422,7 +422,7 @@ func NewCmdUHostDelete(out io.Writer) *cobra.Command {
 				if err != nil {
 					base.HandleError(err)
 				} else {
-					base.Cxt.Printf("uhost:[%s] deleted\n", resp.UHostId)
+					base.Cxt.Printf("uhost[%s] deleted\n", resp.UHostId)
 				}
 			}
 		},

cmd/umem.go

@@ -35,7 +35,7 @@ func NewCmdRedis() *cobra.Command {
 	}
 	out := base.Cxt.GetWriter()
 	cmd.AddCommand(NewCmdRedisList())
-	cmd.AddCommand(NewCmdRedisCreate())
+	cmd.AddCommand(NewCmdRedisCreate(out))
 	cmd.AddCommand(NewCmdRedisDelete(out))
 	return cmd
 }
@@ -147,7 +147,7 @@ func NewCmdRedisList() *cobra.Command {
 }
 
 //NewCmdRedisCreate ucloud redis create
-func NewCmdRedisCreate() *cobra.Command {
+func NewCmdRedisCreate(out io.Writer) *cobra.Command {
 	req := base.BizClient.NewCreateURedisGroupRequest()
 	req.HighAvailability = sdk.String("enable")
 	var redisType, password string
@@ -156,6 +156,10 @@ func NewCmdRedisCreate() *cobra.Command {
 		Short: "Create redis instance",
 		Long:  "Create redis instance",
 		Run: func(c *cobra.Command, args []string) {
+			if l := len(*req.Name); l < 6 || l > 63 {
+				fmt.Fprintln(out, "length of name should be between 6 and 63")
+				return
+			}
 			if redisType == "master-replica" {
 				resp, err := base.BizClient.CreateURedisGroup(req)
 				if err != nil {
@@ -192,7 +196,7 @@ func NewCmdRedisCreate() *cobra.Command {
 	flags := cmd.Flags()
 	flags.SortFlags = false
 
-	req.Name = flags.String("name", "", "Required. Name of the redis to create")
+	req.Name = flags.String("name", "", "Required. Name of the redis to create. Range of the password length is [6,63] and the password can only contain letters and numbers")
 	flags.StringVar(&redisType, "type", "", "Required. Type of the redis. Accept values:'master-replica','distributed'")
 	req.Size = flags.Int("size-gb", 1, "Optional. Memory size. Default value 1GB(for master-replica redis type) or 16GB(for distributed redis type). Unit GB")
 	req.Version = flags.String("version", "3.2", "Optional. Version of redis")

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)