From 5ca77d38744d3481cc0b795f607c5859b19588fc Mon Sep 17 00:00:00 2001
From: Luke Kingland <58986931+lkingland@users.noreply.github.com>
Date: Wed, 16 Nov 2022 23:18:38 +0900
Subject: [PATCH] src: update build command help text (#1425)

* src: build command help text

* Regen docs
---
 cmd/build.go                 | 61 +++++++++++++++++++++++-------------
 docs/reference/func.md       |  2 +-
 docs/reference/func_build.md | 60 +++++++++++++++++++++--------------
 3 files changed, 76 insertions(+), 47 deletions(-)

diff --git a/cmd/build.go b/cmd/build.go
index a0264176bf..4bc3be6ac7 100644
--- a/cmd/build.go
+++ b/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",
-		Long: `Build a function project as a container image
-
-This command builds the function project in the current directory or in the directory
-specified by --path. The result will be a container image that is pushed to a registry.
-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
-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
+		Short: "Build a Function",
+		Long: `
+NAME
+	{{.Name}} build - Build a Function
+
+SYNOPSIS
+	{{.Name}} 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.
+	  $ {{.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
 
-# Build from the local directory, specifying the full image name
-{{.Name}} build --image quay.io/myuser/myfunc
+	o Rebuild a function using prior values to determine container name.
+	  $ {{.Name}} build
 
-# Re-build, picking up a previously supplied image name from a local func.yml
-{{.Name}} build
+	o Build a function specifying the Source-to-Image (S2I) builder
+	  $ {{.Name}} build --builder=s2i
 
-# Build using s2i instead of Buildpacks
-{{.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"),
diff --git a/docs/reference/func.md b/docs/reference/func.md
index 366f4f0278..63a0e103e4 100644
--- a/docs/reference/func.md
+++ b/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
diff --git a/docs/reference/func_build.md b/docs/reference/func_build.md
index cabd9078b9..5034c06c0e 100644
--- a/docs/reference/func_build.md
+++ b/docs/reference/func_build.md
@@ -1,43 +1,55 @@
 ## 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
-specified by --path. The result will be a container image that is pushed to a registry.
-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
-and the image name is stored in the configuration file.
+NAME
+	func build - Build a Function
 
+SYNOPSIS
+	func build [-r|--registry] [--builder] [--builder-image] [--push]
+	             [--palatform] [-p|--path] [-c|--confirm] [-v|--verbose]
 
-```
-func build
-```
+DESCRIPTION
 
-### Examples
+	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.
 
-# 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
+	When building a function for the first time, either a registry or explicit
+	image name is required.  Subsequent builds will reuse these option values.
 
-# Build from the local directory, specifying the full image name
-func build --image quay.io/myuser/myfunc
+EXAMPLES
 
-# Re-build, picking up a previously supplied image name from a local func.yml
-func build
+	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
 
-# Build using s2i instead of Buildpacks
-func build --builder=s2i
+	o Rebuild a function using prior values to determine container name.
+	  $ func build
 
-# Build with a custom buildpack builder
-func build --builder=pack --builder-image cnbs/sample-builder:bionic
+	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
 ```
 
 ### Options