Merge pull request #737 from jcsirot/markdown-cli-examples

Use markdown in CLI examples for automatic documentation generation

Author: jcsirot

internal/commands/build/build.go

@@ -45,14 +45,16 @@ type buildOptions struct {
 	noResolveImage bool
 }
 
+const buildExample = `- $ docker app run --name myrunningapp myrepo/myapp:mytag
+- $ docker app run 34be4a0c5f50 --name myrunningapp`
+
 func Cmd(dockerCli command.Cli) *cobra.Command {
 	var opts buildOptions
 	cmd := &cobra.Command{
-		Use:   "build [OPTIONS] BUILD_PATH",
-		Short: "Build an App image from an App definition (.dockerapp)",
-		Example: `$ docker app build .
-$ docker app build . -f myapp.dockerapp -t myrepo/myapp:1.0.0`,
-		Args: cli.ExactArgs(1),
+		Use:     "build [OPTIONS] BUILD_PATH",
+		Short:   "Build an App image from an App definition (.dockerapp)",
+		Example: buildExample,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runBuild(dockerCli, args[0], opts)
 		},

internal/commands/image/inspect.go

@@ -17,6 +17,11 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const inspectExample = `- $ docker app image inspect myapp
+- $ docker app image inspect myapp:1.0.0
+- $ docker app image inspect myrepo/myapp:1.0.0
+- $ docker app image inspect 34be4a0c5f50`
+
 type inspectOptions struct {
 	pretty bool
 	cliopts.InstallerContextOptions
@@ -34,13 +39,10 @@ func muteDockerCli(dockerCli command.Cli) func() {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [OPTIONS] APP_IMAGE",
-		Short: "Display detailed information about an App image",
-		Example: `$ docker app image inspect myapp
-$ docker app image inspect myapp:1.0.0
-$ docker app image inspect myrepo/myapp:1.0.0
-$ docker app image inspect 34be4a0c5f50`,
-		Args: cli.ExactArgs(1),
+		Use:     "inspect [OPTIONS] APP_IMAGE",
+		Short:   "Display detailed information about an App image",
+		Example: inspectExample,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, args[0], opts)
 		},

internal/commands/image/rm.go

@@ -12,16 +12,18 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const rmExample = `- $ docker app image rm myapp
+- $ docker app image rm myapp:1.0.0
+- $ docker app image rm myrepo/myapp@sha256:c0de...
+- $ docker app image rm 34be4a0c5f50`
+
 func rmCmd() *cobra.Command {
 	return &cobra.Command{
 		Short:   "Remove an App image",
 		Use:     "rm APP_IMAGE [APP_IMAGE...]",
 		Aliases: []string{"remove"},
 		Args:    cli.RequiresMinArgs(1),
-		Example: `$ docker app image rm myapp
-$ docker app image rm myapp:1.0.0
-$ docker app image rm myrepo/myapp@sha256:c0de...
-$ docker app image rm 34be4a0c5f50`,
+		Example: rmExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {

internal/commands/image/tag.go

@@ -12,14 +12,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const tagExample = `- $ docker app image tag myapp myrepo/myapp:mytag
+- $ docker app image tag myapp:tag myrepo/mynewapp:mytag
+- $ docker app image tag 34be4a0c5f50 myrepo/mynewapp:mytag`
+
 func tagCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Create a new tag from an App image",
-		Use:   "tag SOURCE_APP_IMAGE[:TAG] TARGET_APP_IMAGE[:TAG]",
-		Example: `$ docker app image tag myapp myrepo/myapp:mytag
-$ docker app image tag myapp:tag myrepo/mynewapp:mytag
-$ docker app image tag 34be4a0c5f50 myrepo/mynewapp:mytag`,
-		Args: cli.ExactArgs(2),
+		Short:   "Create a new tag from an App image",
+		Use:     "tag SOURCE_APP_IMAGE[:TAG] TARGET_APP_IMAGE[:TAG]",
+		Example: tagExample,
+		Args:    cli.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {

internal/commands/init.go

@@ -13,13 +13,15 @@ var (
 	initComposeFile string
 )
 
+const initExample = `- $ docker app init myapp
+- $ docker app init myapp --compose-file docker-compose.yml`
+
 func initCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "init [OPTIONS] APP_DEFINITION",
-		Short: "Initialize an App definition",
-		Example: `$ docker app init myapp
-$ docker app init myapp --compose-file docker-compose.yml`,
-		Args: cli.ExactArgs(1),
+		Use:     "init [OPTIONS] APP_DEFINITION",
+		Short:   "Initialize an App definition",
+		Example: initExample,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			created, err := packager.Init(dockerCli.Err(), args[0], initComposeFile)
 			if err != nil {

internal/commands/inspect.go

@@ -17,6 +17,9 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const inspectExample = `- $ docker app inspect my-running-app
+- $ docker app inspect my-running-app:1.0.0`
+
 type inspectOptions struct {
 	credentialOptions
 	cliopts.InstallerContextOptions
@@ -28,11 +31,10 @@ type inspectOptions struct {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [OPTIONS] RUNNING_APP",
-		Short: "Shows status, metadata, parameters and the list of services of a running App",
-		Example: `$ docker app inspect my-running-app
-$ docker app inspect my-running-app:1.0.0`,
-		Args: cli.ExactArgs(1),
+		Use:     "inspect [OPTIONS] RUNNING_APP",
+		Short:   "Shows status, metadata, parameters and the list of services of a running App",
+		Example: inspectExample,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, firstOrEmpty(args), opts)
 		},

internal/commands/run.go

@@ -35,8 +35,8 @@ type runOptions struct {
 
 const longDescription = `Run an App from an App image.`
 
-const example = `$ docker app run --name myrunningapp myrepo/myapp:mytag
-$ docker app run 34be4a0c5f50 --name myrunningapp`
+const runExample = `- $ docker app run --name myrunningapp myrepo/myapp:mytag
+- $ docker app run 34be4a0c5f50 --name myrunningapp`
 
 func runCmd(dockerCli command.Cli) *cobra.Command {
 	var opts runOptions
@@ -46,7 +46,7 @@ func runCmd(dockerCli command.Cli) *cobra.Command {
 		Aliases: []string{"deploy"},
 		Short:   "Run an App from an App image",
 		Long:    longDescription,
-		Example: example,
+		Example: runExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if opts.cnabBundle != "" && len(args) != 0 {
 				return errors.Errorf(