From 8e296679efc5df6cee7f302143b1594c454d16a1 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Sirot Date: Tue, 12 Nov 2019 17:18:08 +0100 Subject: [PATCH] Use markdown in CLI examples for automatic documentation generation Signed-off-by: Jean-Christophe Sirot --- internal/commands/build/build.go | 12 +++++++----- internal/commands/image/inspect.go | 16 +++++++++------- internal/commands/image/rm.go | 10 ++++++---- internal/commands/image/tag.go | 14 ++++++++------ internal/commands/init.go | 12 +++++++----- internal/commands/inspect.go | 12 +++++++----- internal/commands/run.go | 6 +++--- 7 files changed, 47 insertions(+), 35 deletions(-) diff --git a/internal/commands/build/build.go b/internal/commands/build/build.go index bc1904082..50f23a81e 100644 --- a/internal/commands/build/build.go +++ b/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) }, diff --git a/internal/commands/image/inspect.go b/internal/commands/image/inspect.go index 9917fc033..5228e020e 100644 --- a/internal/commands/image/inspect.go +++ b/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) }, diff --git a/internal/commands/image/rm.go b/internal/commands/image/rm.go index c2c853009..3afdb88c8 100644 --- a/internal/commands/image/rm.go +++ b/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 { diff --git a/internal/commands/image/tag.go b/internal/commands/image/tag.go index 1cc97b79e..917787f27 100644 --- a/internal/commands/image/tag.go +++ b/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 { diff --git a/internal/commands/init.go b/internal/commands/init.go index 9a02f3ea3..a2039e8e7 100644 --- a/internal/commands/init.go +++ b/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 { diff --git a/internal/commands/inspect.go b/internal/commands/inspect.go index 2e5cc42fc..1778a7831 100644 --- a/internal/commands/inspect.go +++ b/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) }, diff --git a/internal/commands/run.go b/internal/commands/run.go index e4956031e..09279c5a5 100644 --- a/internal/commands/run.go +++ b/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(