src: update build command help text (#1425)

* src: build command help text

* Regen docs

cmd/build.go

@@ -20,32 +20,49 @@ import (
 func NewBuildCmd(newClient ClientFactory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "build",
-		Short: "Build a function project as a container image",
+		Short: "Build a Function",
-		Long: `Build a function project as a container image
+		Long: `
+NAME
+	{{.Name}} build - Build a Function
 
-This command builds the function project in the current directory or in the directory
+SYNOPSIS
-specified by --path. The result will be a container image that is pushed to a registry.
+	{{.Name}} build [-r|--registry] [--builder] [--builder-image] [--push]
-The func.yaml file is read to determine the image name and registry.
+	             [--palatform] [-p|--path] [-c|--confirm] [-v|--verbose]
-If the project has not already been built, either --registry or --image must be provided
-and the image name is stored in the configuration file.
-`,
-		Example: `
-# Build from the local directory, using the given registry as target.
-# The full image name will be determined automatically based on the
-# project directory name
-{{.Name}} build --registry quay.io/myuser
 
-# Build from the local directory, specifying the full image name
+DESCRIPTION
-{{.Name}} build --image quay.io/myuser/myfunc
 
-# Re-build, picking up a previously supplied image name from a local func.yml
+	Builds a function's container image and optionally pushes it to the
-{{.Name}} build
+	configured container registry.
 
-# Build using s2i instead of Buildpacks
+	By default building is handled automatically when deploying (see the deploy
-{{.Name}} build --builder=s2i
+	subcommand). However, sometimes it is useful to build a function container
+	outside of this normal deployment process, for example for testing or during
+	composition when integrationg with other systems. Additionally, the container
+	can be pushed to the configured registry using the --push option.
+
+	When building a function for the first time, either a registry or explicit
+	image name is required.  Subsequent builds will reuse these option values.
+
+EXAMPLES
+
+	o Build a function container using the given registry.
+	  The full image name will be calculated using the registry and function name.
+	  $ {{.Name}} build --registry registry.example.com/alice
+
+	o Build a function container using an explicit image name, ignoring registry
+	  and function name.
+		$ {{.Name}} build --image registry.example.com/alice/f:latest
+
+	o Rebuild a function using prior values to determine container name.
+	  $ {{.Name}} build
+
+	o Build a function specifying the Source-to-Image (S2I) builder
+	  $ {{.Name}} build --builder=s2i
+
+	o Build a function specifying the Pack builder with a custom Buildpack
+	  builder image.
+		$ {{.Name}} build --builder=pack --builder-image=cnbs/sample-builder:bionic
 
-# Build with a custom buildpack builder
-{{.Name}} build --builder=pack --builder-image cnbs/sample-builder:bionic
 `,
 		SuggestFor: []string{"biuld", "buidl", "built"},
 		PreRunE:    bindEnv("image", "path", "builder", "registry", "confirm", "push", "builder-image", "platform"),

docs/reference/func.md

@@ -36,7 +36,7 @@ EXAMPLES
 
 ### SEE ALSO
 
-* [func build](func_build.md)	 - Build a function project as a container image
+* [func build](func_build.md)	 - Build a Function
 * [func completion](func_completion.md)	 - Generate completion scripts for bash, fish and zsh
 * [func config](func_config.md)	 - Configure a function
 * [func create](func_create.md)	 - Create a function project

docs/reference/func_build.md

@@ -1,45 +1,57 @@
 ## func build
 
-Build a function project as a container image
+Build a Function
 
 ### Synopsis
 
-Build a function project as a container image
 
-This command builds the function project in the current directory or in the directory
+NAME
-specified by --path. The result will be a container image that is pushed to a registry.
+	func build - Build a Function
-The func.yaml file is read to determine the image name and registry.
+
-If the project has not already been built, either --registry or --image must be provided
+SYNOPSIS
-and the image name is stored in the configuration file.
+	func build [-r|--registry] [--builder] [--builder-image] [--push]
+	             [--palatform] [-p|--path] [-c|--confirm] [-v|--verbose]
+
+DESCRIPTION
+
+	Builds a function's container image and optionally pushes it to the
+	configured container registry.
+
+	By default building is handled automatically when deploying (see the deploy
+	subcommand). However, sometimes it is useful to build a function container
+	outside of this normal deployment process, for example for testing or during
+	composition when integrationg with other systems. Additionally, the container
+	can be pushed to the configured registry using the --push option.
+
+	When building a function for the first time, either a registry or explicit
+	image name is required.  Subsequent builds will reuse these option values.
+
+EXAMPLES
+
+	o Build a function container using the given registry.
+	  The full image name will be calculated using the registry and function name.
+	  $ func build --registry registry.example.com/alice
+
+	o Build a function container using an explicit image name, ignoring registry
+	  and function name.
+		$ func build --image registry.example.com/alice/f:latest
+
+	o Rebuild a function using prior values to determine container name.
+	  $ func build
+
+	o Build a function specifying the Source-to-Image (S2I) builder
+	  $ func build --builder=s2i
+
+	o Build a function specifying the Pack builder with a custom Buildpack
+	  builder image.
+		$ func build --builder=pack --builder-image=cnbs/sample-builder:bionic
+
 
 
 ```
 func build
 ```
 
-### Examples
-
-```
-
-# Build from the local directory, using the given registry as target.
-# The full image name will be determined automatically based on the
-# project directory name
-func build --registry quay.io/myuser
-
-# Build from the local directory, specifying the full image name
-func build --image quay.io/myuser/myfunc
-
-# Re-build, picking up a previously supplied image name from a local func.yml
-func build
-
-# Build using s2i instead of Buildpacks
-func build --builder=s2i
-
-# Build with a custom buildpack builder
-func build --builder=pack --builder-image cnbs/sample-builder:bionic
-
-```
-
 ### Options
 
 ```