Allow multiline examples for custom commands (#2495)

cmd/ddev/cmd/commands.go

@@ -108,7 +108,7 @@ func addCustomCommands(rootCmd *cobra.Command) error {
 					usage = val
 				}
 				if val, ok := directives["Example"]; ok {
-					example = val
+					example = "  " + strings.ReplaceAll(val, `\n`, "\n  ")
 				}
 				if val, ok := directives["ProjectTypes"]; ok {
 					projectTypes = val

cmd/ddev/cmd/commands_test.go

@@ -2,6 +2,13 @@ package cmd
 
 import (
 	"fmt"
+	"os"
+	osexec "os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
 	"github.com/drud/ddev/pkg/ddevapp"
 	"github.com/drud/ddev/pkg/exec"
 	"github.com/drud/ddev/pkg/fileutil"
@@ -10,12 +17,6 @@ import (
 	"github.com/drud/ddev/pkg/util"
 	asrt "github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"os"
-	osexec "os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
 )
 
 // TestCustomCommands does basic checks to make sure custom commands work OK.
@@ -111,6 +112,14 @@ func TestCustomCommands(t *testing.T) {
 		assert.Contains(out, fmt.Sprintf("%s was executed with args=hostarg1 hostarg2 --hostflag1 on host %s", c, expectedHost))
 	}
 
+	// Test line breaks in examples
+	c := "testhostcmd"
+	args := []string{c, "-h"}
+	out, err = exec.RunCommand(DdevBin, args)
+	assert.NoError(err, "Failed to run ddev %s %v", c, args)
+	assert.Contains(out, "Examples:\n  ddev testhostcmd\n  ddev testhostcmd -h")
+
+	// Provide app configuration
 	app.Type = nodeps.AppTypePHP
 	err = app.WriteConfig()
 	assert.NoError(err)

cmd/ddev/cmd/testdata/TestCustomCommands/project_commands/host/testhostcmd

@@ -2,6 +2,6 @@
 
 ## Description: testhostcmd project
 ## Usage: testhostcmd
-## Example: "ddev testhostcmd"
+## Example: ddev testhostcmd\nddev testhostcmd -h
 
 echo "testhostcmd was executed with args=$@ on host $(hostname)"

docs/users/extend/custom-commands.md

@@ -102,6 +102,16 @@ Useful variables for container scripts are:
 * DDEV_WEBSERVER_TYPE: nginx-fpm, apache-fpm
 * IS_DDEV_PROJECT: if set to "true" it means that php is running under DDEV
 
+### Annotations supported
+
+The custom commands support various annotations in the header which are used to provide additional information about the command to the user:
+
+* Description
+* Usage
+* Example (use `\n` to force a line break)
+* ProjectTypes
+* OSTypes
+
 ### Known Windows OS issues
 
 * **Line Endings**: If you are editing a custom command which will run in a container, it must have LF line endings (not traditional Windows CRLF line endings). Remember that a custom command in a container is a script that must execute in a Linux environmet.