update docs and examples (#601)

(cherry picked from commit e24cd2b)

Author: ospillinger

README.md

@@ -102,8 +102,8 @@ The CLI sends configuration and code to the cluster every time you run `cortex d
 
 ## Examples
 
-<!-- CORTEX_VERSION_README_MINOR x4 -->
-- [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/sentiment-analysis) in TensorFlow with BERT
+<!-- CORTEX_VERSION_README_MINOR x5 -->
+- [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/sentiment-analyzer) in TensorFlow with BERT
 - [Image classification](https://github.com/cortexlabs/cortex/tree/0.11/examples/tensorflow/image-classifier) in TensorFlow with Inception
 - [Text generation](https://github.com/cortexlabs/cortex/tree/0.11/examples/pytorch/text-generator) in PyTorch with DistilGPT2
 - [Reading comprehension](https://github.com/cortexlabs/cortex/tree/0.11/examples/pytorch/text-generator) in PyTorch with ELMo-BiDAF

cli/cmd/cluster.go

@@ -57,20 +57,18 @@ func init() {
 }
 
 func addClusterConfigFlag(cmd *cobra.Command) {
-	cmd.PersistentFlags().StringVarP(&flagClusterConfig, "config", "c", "", "path to a Cortex cluster configuration file")
+	cmd.PersistentFlags().StringVarP(&flagClusterConfig, "config", "c", "", "path to a cluster configuration file")
 	cmd.PersistentFlags().SetAnnotation("config", cobra.BashCompFilenameExt, configFileExts)
 }
 
 var clusterCmd = &cobra.Command{
 	Use:   "cluster",
-	Short: "manage a Cortex cluster",
-	Long:  "Manage a Cortex cluster",
+	Short: "manage a cluster",
 }
 
 var upCmd = &cobra.Command{
 	Use:   "up",
-	Short: "spin up a Cortex cluster",
-	Long:  `This command spins up a Cortex cluster on your AWS account.`,
+	Short: "spin up a cluster",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := checkDockerRunning(); err != nil {
@@ -97,8 +95,7 @@ var upCmd = &cobra.Command{
 
 var updateCmd = &cobra.Command{
 	Use:   "update",
-	Short: "update a Cortex cluster",
-	Long:  `This command updates a Cortex cluster.`,
+	Short: "update a cluster",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := checkDockerRunning(); err != nil {
@@ -126,8 +123,7 @@ var updateCmd = &cobra.Command{
 
 var infoCmd = &cobra.Command{
 	Use:   "info",
-	Short: "get information about a Cortex cluster",
-	Long:  `This command gets information about a Cortex cluster.`,
+	Short: "get information about a cluster",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := checkDockerRunning(); err != nil {
@@ -145,7 +141,9 @@ var infoCmd = &cobra.Command{
 		if err != nil {
 			errors.Exit(err)
 		}
-		if strings.Contains(out, "there isn't a cortex cluster") {
+
+		// note: if modifying this string, search the codebase for it and change all occurrences
+		if strings.Contains(out, "there is no cluster") {
 			errors.Exit()
 		}
 
@@ -176,8 +174,7 @@ var infoCmd = &cobra.Command{
 
 var downCmd = &cobra.Command{
 	Use:   "down",
-	Short: "spin down a Cortex cluster",
-	Long:  `This command spins down a Cortex cluster.`,
+	Short: "spin down a cluster",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := checkDockerRunning(); err != nil {
@@ -267,14 +264,16 @@ func refreshCachedClusterConfig(awsCreds *AWSCredentials) *clusterconfig.Cluster
 	}
 
 	if userClusterConfig.Region == nil {
-		errors.Exit(fmt.Sprintf("unable to find an existing cortex cluster; please configure \"%s\" to the s3 region of an existing cortex cluster or create a cortex cluster with `cortex cluster up`", clusterconfig.RegionKey))
+		errors.Exit(fmt.Sprintf("unable to find an existing cluster; please configure \"%s\" to the s3 region of an existing cluster or create a cluster with `cortex cluster up`", clusterconfig.RegionKey))
 	}
 
 	out, err := runRefreshClusterConfig(userClusterConfig, awsCreds)
 	if err != nil {
 		errors.Exit(err)
 	}
-	if strings.Contains(out, "there isn't a cortex cluster") {
+
+	// note: if modifying this string, search the codebase for it and change all occurrences
+	if strings.Contains(out, "there is no cluster") {
 		errors.Exit()
 	}
 

cli/cmd/completion.go

@@ -26,16 +26,15 @@ import (
 var completionCmd = &cobra.Command{
 	Use:   "completion",
 	Short: "generate bash completion scripts",
-	Long: `Generate bash completion scripts.
+	Long: `generate bash completion scripts
 
-Add this to your bashrc or bash profile:
+add this to your bashrc or bash profile:
   source <(cortex completion)
-Or run:
-  echo 'source <(cortex completion)' >> ~/.bash_profile  # Mac
-  echo 'source <(cortex completion)' >> ~/.bashrc  # Linux
+or run:
+  echo 'source <(cortex completion)' >> ~/.bash_profile  # mac
+  echo 'source <(cortex completion)' >> ~/.bashrc  # linux
 
-This will also add the "cx" alias.
-Note: Cortex CLI completion requires the bash_completion package to be installed on your system.
+this will also add the "cx" alias (note: cli completion requires the bash_completion package to be installed on your system)
 `,
 	Args: cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {

cli/cmd/configure.go

@@ -33,11 +33,8 @@ func init() {
 
 var configureCmd = &cobra.Command{
 	Use:   "configure",
-	Short: "configure the CLI",
-	Long: `This command configures the Cortex URL and AWS credentials
-in order to authenticate and send requests to Cortex.
-The configuration is stored in ~/.cortex.`,
-	Args: cobra.NoArgs,
+	Short: "configure the cli",
+	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		if flagPrint {
 			cliConfig := getDefaults()

cli/cmd/delete.go

@@ -38,7 +38,6 @@ func init() {
 var deleteCmd = &cobra.Command{
 	Use:   "delete [DEPLOYMENT_NAME]",
 	Short: "delete a deployment",
-	Long:  `This command deletes a deployment from the cluster.`,
 	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		var appName string

cli/cmd/deploy.go

@@ -38,16 +38,14 @@ var flagDeployRefresh bool
 
 func init() {
 	deployCmd.PersistentFlags().BoolVarP(&flagDeployForce, "force", "f", false, "override the in-progress deployment update")
-	deployCmd.PersistentFlags().BoolVarP(&flagDeployRefresh, "refresh", "r", false, "re-deploy all APIs with cleared cache and rolling updates")
+	deployCmd.PersistentFlags().BoolVarP(&flagDeployRefresh, "refresh", "r", false, "re-deploy all apis with cleared cache and rolling updates")
 	addEnvFlag(deployCmd)
 }
 
 var deployCmd = &cobra.Command{
 	Use:   "deploy",
 	Short: "create or update a deployment",
-	Long: `This command sends all project configuration and code to Cortex.
-If validations pass, Cortex will attempt to create the desired state.`,
-	Args: cobra.NoArgs,
+	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		deploy(flagDeployForce, flagDeployRefresh)
 	},

cli/cmd/errors.go

@@ -129,7 +129,7 @@ func ErrorFailedConnectURL(url url.URL) error {
 func ErrorFailedToConnectOperator(urlStr string) error {
 	return Error{
 		Kind:    ErrFailedToConnectOperator,
-		message: fmt.Sprintf("failed to connect to the operator (%s), run `cortex configure` if you need to update the operator URL", urlStr),
+		message: fmt.Sprintf("failed to connect to the operator (%s), run `cortex configure` if you need to update the operator endpoint", urlStr),
 	}
 }
 

cli/cmd/get.go

@@ -57,10 +57,8 @@ func init() {
 
 var getCmd = &cobra.Command{
 	Use:   "get [API_NAME]",
-	Short: "get information about APIs",
-	Long: `This command displays information about APIs.
-Adding the -v or --verbose flag displays additional information.`,
-	Args: cobra.RangeArgs(0, 1),
+	Short: "get information about deployments",
+	Args:  cobra.RangeArgs(0, 1),
 	Run: func(cmd *cobra.Command, args []string) {
 		rerun(func() (string, error) {
 			return runGet(cmd, args)
@@ -424,7 +422,7 @@ func classificationMetricsTable(apiMetrics schema.APIMetrics) string {
 
 func describeModelInput(groupStatus *resource.APIGroupStatus, apiEndpoint string) string {
 	if groupStatus.ReadyUpdated+groupStatus.ReadyStaleCompute == 0 {
-		return "the model's input schema will be available when the API is live"
+		return "the model's input schema will be available when the api is live"
 	}
 
 	apiSummary, err := getAPISummary(apiEndpoint)
@@ -462,7 +460,7 @@ func describeModelInput(groupStatus *resource.APIGroupStatus, apiEndpoint string
 func getAPISummary(apiEndpoint string) (*schema.APISummary, error) {
 	req, err := http.NewRequest("GET", apiEndpoint, nil)
 	if err != nil {
-		return nil, errors.Wrap(err, "unable to request API summary")
+		return nil, errors.Wrap(err, "unable to request api summary")
 	}
 	req.Header.Set("Content-Type", "application/json")
 	response, err := httpsNoVerifyClient.makeRequest(req)
@@ -473,7 +471,7 @@ func getAPISummary(apiEndpoint string) (*schema.APISummary, error) {
 	var apiSummary schema.APISummary
 	err = json.DecodeWithNumber(response, &apiSummary)
 	if err != nil {
-		return nil, errors.Wrap(err, "unable to parse API summary response")
+		return nil, errors.Wrap(err, "unable to parse api summary response")
 	}
 
 	for _, featureSignature := range apiSummary.ModelSignature {

cli/cmd/logs.go

@@ -31,8 +31,7 @@ func init() {
 
 var logsCmd = &cobra.Command{
 	Use:   "logs API_NAME",
-	Short: "get logs for an API",
-	Long:  `This command streams logs from a deployed API.`,
+	Short: "stream logs from an api",
 	Args:  cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		resourceName := args[0]

cli/cmd/predict.go

@@ -35,15 +35,13 @@ var predictDebug bool
 func init() {
 	addAppNameFlag(predictCmd)
 	addEnvFlag(predictCmd)
-	predictCmd.Flags().BoolVar(&predictDebug, "debug", false, "Predict with debug mode")
+	predictCmd.Flags().BoolVar(&predictDebug, "debug", false, "predict with debug mode")
 }
 
 var predictCmd = &cobra.Command{
 	Use:   "predict API_NAME SAMPLE_FILE",
-	Short: "make a prediction request",
-	Long: `This command makes a prediction request using
-a JSON file and displays the response.`,
-	Args: cobra.ExactArgs(2),
+	Short: "make a prediction request using a json file",
+	Args:  cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		apiName := args[0]
 		sampleJSONPath := args[1]