From 42710b7c4356ef9b196b07a3286d35f7692e625d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 9 Mar 2022 12:57:07 +0100 Subject: [PATCH] docs: also generate "usage" in MarkDown files Signed-off-by: Sebastiaan van Stijn --- docs/reference/compose.md | 50 ++++++++++++++++++++++ docs/reference/compose_build.md | 17 ++++++++ docs/reference/compose_convert.md | 26 +++++++++++ docs/reference/compose_cp.md | 17 ++++++++ docs/reference/compose_create.md | 17 ++++++++ docs/reference/compose_down.md | 15 +++++++ docs/reference/compose_events.md | 13 ++++++ docs/reference/compose_exec.md | 19 ++++++++ docs/reference/compose_images.md | 14 ++++++ docs/reference/compose_kill.md | 13 ++++++ docs/reference/compose_logs.md | 19 ++++++++ docs/reference/compose_ls.md | 16 +++++++ docs/reference/compose_pause.md | 7 +++ docs/reference/compose_port.md | 14 ++++++ docs/reference/compose_ps.md | 17 ++++++++ docs/reference/compose_pull.md | 15 +++++++ docs/reference/compose_push.md | 13 ++++++ docs/reference/compose_restart.md | 16 +++++++ docs/reference/compose_rm.md | 20 +++++++++ docs/reference/compose_run.md | 28 ++++++++++++ docs/reference/compose_start.md | 7 +++ docs/reference/compose_stop.md | 13 ++++++ docs/reference/compose_top.md | 7 +++ docs/reference/compose_unpause.md | 7 +++ docs/reference/compose_up.md | 32 ++++++++++++++ docs/reference/compose_version.md | 14 ++++++ docs/reference/docker_compose_restart.yaml | 12 +++++- docs/yaml/main/generate.go | 6 +-- 28 files changed, 460 insertions(+), 4 deletions(-) diff --git a/docs/reference/compose.md b/docs/reference/compose.md index 03bc6f400..e5c27fa75 100644 --- a/docs/reference/compose.md +++ b/docs/reference/compose.md @@ -1,4 +1,54 @@ +# docker compose + +Docker Compose + +### Subcommands + +| Name | Description | +| --- | --- | +| [`build`](compose_build.md) | Build or rebuild services | +| [`convert`](compose_convert.md) | Converts the compose file to platform's canonical format | +| [`cp`](compose_cp.md) | Copy files/folders between a service container and the local filesystem | +| [`create`](compose_create.md) | Creates containers for a service. | +| [`down`](compose_down.md) | Stop and remove containers, networks | +| [`events`](compose_events.md) | Receive real time events from containers. | +| [`exec`](compose_exec.md) | Execute a command in a running container. | +| [`images`](compose_images.md) | List images used by the created containers | +| [`kill`](compose_kill.md) | Force stop service containers. | +| [`logs`](compose_logs.md) | View output from containers | +| [`ls`](compose_ls.md) | List running compose projects | +| [`pause`](compose_pause.md) | Pause services | +| [`port`](compose_port.md) | Print the public port for a port binding. | +| [`ps`](compose_ps.md) | List containers | +| [`pull`](compose_pull.md) | Pull service images | +| [`push`](compose_push.md) | Push service images | +| [`restart`](compose_restart.md) | Restart containers | +| [`rm`](compose_rm.md) | Removes stopped service containers | +| [`run`](compose_run.md) | Run a one-off command on a service. | +| [`start`](compose_start.md) | Start services | +| [`stop`](compose_stop.md) | Stop services | +| [`top`](compose_top.md) | Display the running processes | +| [`unpause`](compose_unpause.md) | Unpause services | +| [`up`](compose_up.md) | Create and start containers | +| [`version`](compose_version.md) | Show the Docker Compose version information | + + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--ansi` | `string` | `auto` | Control when to print ANSI control characters ("never"\|"always"\|"auto") | +| `--compatibility` | | | Run compose in backward compatibility mode | +| `--env-file` | `string` | | Specify an alternate environment file. | +| `-f`, `--file` | `stringArray` | | Compose configuration files | +| `--profile` | `stringArray` | | Specify a profile to enable | +| `--project-directory` | `string` | | Specify an alternate working directory +(default: the path of the Compose file) | +| `-p`, `--project-name` | `string` | | Project name | + + + ## Description diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md index d42f0a53b..dbb3a4692 100644 --- a/docs/reference/compose_build.md +++ b/docs/reference/compose_build.md @@ -1,3 +1,20 @@ +# docker compose build + + +Build or rebuild services + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--build-arg` | `stringArray` | | Set build-time variables for services. | +| `--no-cache` | | | Do not use cache when building the image | +| `--progress` | `string` | `auto` | Set type of progress output (auto, tty, plain, quiet) | +| `--pull` | | | Always attempt to pull a newer version of the image. | +| `-q`, `--quiet` | | | Don't print anything to STDOUT | + + + ## Description diff --git a/docs/reference/compose_convert.md b/docs/reference/compose_convert.md index ca421d5f0..91ff89ea9 100644 --- a/docs/reference/compose_convert.md +++ b/docs/reference/compose_convert.md @@ -1,4 +1,30 @@ +# docker compose convert + +Converts the compose file to platform's canonical format + +### Aliases + +`convert`, `config` + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--format` | `string` | `yaml` | Format the output. Values: [yaml \| json] | +| `--hash` | `string` | | Print the service config hash, one per line. | +| `--images` | | | Print the image names, one per line. | +| `--no-interpolate` | | | Don't interpolate environment variables. | +| `--no-normalize` | | | Don't normalize compose model. | +| `-o`, `--output` | `string` | | Save to file (default to stdout) | +| `--profiles` | | | Print the profile names, one per line. | +| `-q`, `--quiet` | | | Only validate the configuration, don't print anything. | +| `--resolve-image-digests` | | | Pin image tags to digests. | +| `--services` | | | Print the service names, one per line. | +| `--volumes` | | | Print the volume names, one per line. | + + + ## Description diff --git a/docs/reference/compose_cp.md b/docs/reference/compose_cp.md index e69de29bb..2d97b9f2f 100644 --- a/docs/reference/compose_cp.md +++ b/docs/reference/compose_cp.md @@ -0,0 +1,17 @@ +# docker compose cp + + +Copy files/folders between a service container and the local filesystem + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--all` | | | Copy to all the containers of the service. | +| `-a`, `--archive` | | | Archive mode (copy all uid/gid information) | +| `-L`, `--follow-link` | | | Always follow symbol link in SRC_PATH | +| `--index` | `int` | `1` | Index of the container if there are multiple instances of a service [default: 1]. | + + + + diff --git a/docs/reference/compose_create.md b/docs/reference/compose_create.md index e69de29bb..00123ba78 100644 --- a/docs/reference/compose_create.md +++ b/docs/reference/compose_create.md @@ -0,0 +1,17 @@ +# docker compose create + + +Creates containers for a service. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--build` | | | Build images before starting containers. | +| `--force-recreate` | | | Recreate containers even if their configuration and image haven't changed. | +| `--no-build` | | | Don't build an image, even if it's missing. | +| `--no-recreate` | | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | + + + + diff --git a/docs/reference/compose_down.md b/docs/reference/compose_down.md index 1cc21d81a..8864aa6e8 100644 --- a/docs/reference/compose_down.md +++ b/docs/reference/compose_down.md @@ -1,4 +1,19 @@ +# docker compose down + +Stop and remove containers, networks + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--remove-orphans` | | | Remove containers for services not defined in the Compose file. | +| `--rmi` | `string` | | Remove images used by services. "local" remove only images that don't have a custom tag ("local"\|"all") | +| `-t`, `--timeout` | `int` | `10` | Specify a shutdown timeout in seconds | +| `-v`, `--volumes` | | | Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers. | + + + ## Description diff --git a/docs/reference/compose_events.md b/docs/reference/compose_events.md index 4225974a9..496d204e3 100644 --- a/docs/reference/compose_events.md +++ b/docs/reference/compose_events.md @@ -1,3 +1,16 @@ +# docker compose events + + +Receive real time events from containers. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--json` | | | Output events as a stream of json objects | + + + ## Description diff --git a/docs/reference/compose_exec.md b/docs/reference/compose_exec.md index d6fa981ee..9dd818b9f 100644 --- a/docs/reference/compose_exec.md +++ b/docs/reference/compose_exec.md @@ -1,3 +1,22 @@ +# docker compose exec + + +Execute a command in a running container. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-d`, `--detach` | | | Detached mode: Run command in the background. | +| `-e`, `--env` | `stringArray` | | Set environment variables | +| `--index` | `int` | `1` | index of the container if there are multiple instances of a service [default: 1]. | +| `-T`, `--no-TTY` | | | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. | +| `--privileged` | | | Give extended privileges to the process. | +| `-u`, `--user` | `string` | | Run the command as this user. | +| `-w`, `--workdir` | `string` | | Path to workdir directory for this command. | + + + ## Description diff --git a/docs/reference/compose_images.md b/docs/reference/compose_images.md index e69de29bb..cfb0ad2cd 100644 --- a/docs/reference/compose_images.md +++ b/docs/reference/compose_images.md @@ -0,0 +1,14 @@ +# docker compose images + + +List images used by the created containers + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-q`, `--quiet` | | | Only display IDs | + + + + diff --git a/docs/reference/compose_kill.md b/docs/reference/compose_kill.md index cb8fb249a..d0512faae 100644 --- a/docs/reference/compose_kill.md +++ b/docs/reference/compose_kill.md @@ -1,3 +1,16 @@ +# docker compose kill + + +Force stop service containers. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-s`, `--signal` | `string` | `SIGKILL` | SIGNAL to send to the container. | + + + ## Description diff --git a/docs/reference/compose_logs.md b/docs/reference/compose_logs.md index f325e0a7f..4f9690a7e 100644 --- a/docs/reference/compose_logs.md +++ b/docs/reference/compose_logs.md @@ -1,3 +1,22 @@ +# docker compose logs + + +View output from containers + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-f`, `--follow` | | | Follow log output. | +| `--no-color` | | | Produce monochrome output. | +| `--no-log-prefix` | | | Don't print prefix in logs. | +| `--since` | `string` | | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | +| `--tail` | `string` | `all` | Number of lines to show from the end of the logs for each container. | +| `-t`, `--timestamps` | | | Show timestamps. | +| `--until` | `string` | | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) | + + + ## Description diff --git a/docs/reference/compose_ls.md b/docs/reference/compose_ls.md index 19ff6de7f..b172c7f3a 100644 --- a/docs/reference/compose_ls.md +++ b/docs/reference/compose_ls.md @@ -1,3 +1,19 @@ +# docker compose ls + + +List running compose projects + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-a`, `--all` | | | Show all stopped Compose projects | +| `--filter` | `filter` | | Filter output based on conditions provided. | +| `--format` | `string` | `pretty` | Format the output. Values: [pretty \| json]. | +| `-q`, `--quiet` | | | Only display IDs. | + + + ## Description diff --git a/docs/reference/compose_pause.md b/docs/reference/compose_pause.md index acbf1ff28..dd34191bd 100644 --- a/docs/reference/compose_pause.md +++ b/docs/reference/compose_pause.md @@ -1,3 +1,10 @@ +# docker compose pause + + +Pause services + + + ## Description diff --git a/docs/reference/compose_port.md b/docs/reference/compose_port.md index b78d0837c..8ab893f0d 100644 --- a/docs/reference/compose_port.md +++ b/docs/reference/compose_port.md @@ -1,3 +1,17 @@ +# docker compose port + + +Print the public port for a port binding. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--index` | `int` | `1` | index of the container if service has multiple replicas | +| `--protocol` | `string` | `tcp` | tcp or udp | + + + ## Description diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index 30e6dcbf4..64551397e 100644 --- a/docs/reference/compose_ps.md +++ b/docs/reference/compose_ps.md @@ -1,3 +1,20 @@ +# docker compose ps + + +List containers + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-a`, `--all` | | | Show all stopped containers (including those created by the run command) | +| `--format` | `string` | `pretty` | Format the output. Values: [pretty \| json] | +| `-q`, `--quiet` | | | Only display IDs | +| `--services` | | | Display services | +| `--status` | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] | + + + ## Description diff --git a/docs/reference/compose_pull.md b/docs/reference/compose_pull.md index 7a76a44c5..c081c2284 100644 --- a/docs/reference/compose_pull.md +++ b/docs/reference/compose_pull.md @@ -1,3 +1,18 @@ +# docker compose pull + + +Pull service images + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--ignore-pull-failures` | | | Pull what it can and ignores images with pull failures | +| `--include-deps` | | | Also pull services declared as dependencies | +| `-q`, `--quiet` | | | Pull without printing progress information | + + + ## Description diff --git a/docs/reference/compose_push.md b/docs/reference/compose_push.md index 9015d961a..a1569cc80 100644 --- a/docs/reference/compose_push.md +++ b/docs/reference/compose_push.md @@ -1,3 +1,16 @@ +# docker compose push + + +Push service images + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--ignore-push-failures` | | | Push what it can and ignores images with push failures | + + + ## Description diff --git a/docs/reference/compose_restart.md b/docs/reference/compose_restart.md index 65cebc080..12326662b 100644 --- a/docs/reference/compose_restart.md +++ b/docs/reference/compose_restart.md @@ -1,3 +1,19 @@ +# docker compose restart + + +Restart containers + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-t`, `--timeout` | `int` | `10` | Specify a shutdown timeout in seconds | + + + + +## Description + Restarts all stopped and running services. If you make changes to your `compose.yml` configuration, these changes are not reflected diff --git a/docs/reference/compose_rm.md b/docs/reference/compose_rm.md index da4584882..017c7f122 100644 --- a/docs/reference/compose_rm.md +++ b/docs/reference/compose_rm.md @@ -1,3 +1,23 @@ +# docker compose rm + + +Removes stopped service containers + +By default, anonymous volumes attached to containers will not be removed. You +can override this with -v. To list all volumes, use "docker volume ls". + +Any data which is not in a volume will be lost. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-f`, `--force` | | | Don't ask to confirm removal | +| `-s`, `--stop` | | | Stop the containers, if required, before removing | +| `-v`, `--volumes` | | | Remove any anonymous volumes attached to containers | + + + ## Description diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md index e73def59e..6d8c3e959 100644 --- a/docs/reference/compose_run.md +++ b/docs/reference/compose_run.md @@ -1,3 +1,31 @@ +# docker compose run + + +Run a one-off command on a service. + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-d`, `--detach` | | | Run container in background and print container ID | +| `--entrypoint` | `string` | | Override the entrypoint of the image | +| `-e`, `--env` | `stringArray` | | Set environment variables | +| `-i`, `--interactive` | | | Keep STDIN open even if not attached. | +| `-l`, `--label` | `stringArray` | | Add or override a label | +| `--name` | `string` | | Assign a name to the container | +| `-T`, `--no-TTY` | | | Disable pseudo-noTty allocation. By default docker compose run allocates a TTY | +| `--no-deps` | | | Don't start linked services. | +| `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host. | +| `--quiet-pull` | | | Pull without printing progress information. | +| `--rm` | | | Automatically remove the container when it exits | +| `--service-ports` | | | Run command with the service's ports enabled and mapped to the host. | +| `--use-aliases` | | | Use the service's network useAliases in the network(s) the container connects to. | +| `-u`, `--user` | `string` | | Run as specified username or uid | +| `-v`, `--volume` | `stringArray` | | Bind mount a volume. | +| `-w`, `--workdir` | `string` | | Working directory inside the container | + + + ## Description diff --git a/docs/reference/compose_start.md b/docs/reference/compose_start.md index 569dfe58e..8f8cb5b48 100644 --- a/docs/reference/compose_start.md +++ b/docs/reference/compose_start.md @@ -1,3 +1,10 @@ +# docker compose start + + +Start services + + + ## Description diff --git a/docs/reference/compose_stop.md b/docs/reference/compose_stop.md index 5d5c5db90..9d8ead823 100644 --- a/docs/reference/compose_stop.md +++ b/docs/reference/compose_stop.md @@ -1,3 +1,16 @@ +# docker compose stop + + +Stop services + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-t`, `--timeout` | `int` | `10` | Specify a shutdown timeout in seconds | + + + ## Description diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md index e70f4341a..eee5a3cab 100644 --- a/docs/reference/compose_top.md +++ b/docs/reference/compose_top.md @@ -1,3 +1,10 @@ +# docker compose top + + +Display the running processes + + + ## Description diff --git a/docs/reference/compose_unpause.md b/docs/reference/compose_unpause.md index b071841a8..e819c0c4f 100644 --- a/docs/reference/compose_unpause.md +++ b/docs/reference/compose_unpause.md @@ -1,3 +1,10 @@ +# docker compose unpause + + +Unpause services + + + ## Description diff --git a/docs/reference/compose_up.md b/docs/reference/compose_up.md index 7ff40855f..1a110f3f9 100644 --- a/docs/reference/compose_up.md +++ b/docs/reference/compose_up.md @@ -1,3 +1,35 @@ +# docker compose up + + +Create and start containers + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--abort-on-container-exit` | | | Stops all containers if any container was stopped. Incompatible with -d | +| `--always-recreate-deps` | | | Recreate dependent containers. Incompatible with --no-recreate. | +| `--attach` | `stringArray` | | Attach to service output. | +| `--attach-dependencies` | | | Attach to dependent containers. | +| `--build` | | | Build images before starting containers. | +| `-d`, `--detach` | | | Detached mode: Run containers in the background | +| `--exit-code-from` | `string` | | Return the exit code of the selected service container. Implies --abort-on-container-exit | +| `--force-recreate` | | | Recreate containers even if their configuration and image haven't changed. | +| `--no-build` | | | Don't build an image, even if it's missing. | +| `--no-color` | | | Produce monochrome output. | +| `--no-deps` | | | Don't start linked services. | +| `--no-log-prefix` | | | Don't print prefix in logs. | +| `--no-recreate` | | | If containers already exist, don't recreate them. Incompatible with --force-recreate. | +| `--no-start` | | | Don't start the services after creating them. | +| `--quiet-pull` | | | Pull without printing progress information. | +| `--remove-orphans` | | | Remove containers for services not defined in the Compose file. | +| `-V`, `--renew-anon-volumes` | | | Recreate anonymous volumes instead of retrieving data from the previous containers. | +| `--scale` | `stringArray` | | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. | +| `-t`, `--timeout` | `int` | `10` | Use this timeout in seconds for container shutdown when attached or when containers are already running. | +| `--wait` | | | Wait for services to be running\|healthy. Implies detached mode. | + + + ## Description diff --git a/docs/reference/compose_version.md b/docs/reference/compose_version.md index e69de29bb..94b2d36dc 100644 --- a/docs/reference/compose_version.md +++ b/docs/reference/compose_version.md @@ -0,0 +1,14 @@ +# docker compose version + + +Show the Docker Compose version information + +### Options + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `-f`, `--format` | `string` | | Format the output. Values: [pretty \| json]. (Default: pretty) | +| `--short` | | | Shows only Compose's version number. | + + + diff --git a/docs/reference/docker_compose_restart.yaml b/docs/reference/docker_compose_restart.yaml index e94596c74..9f646cc07 100644 --- a/docs/reference/docker_compose_restart.yaml +++ b/docs/reference/docker_compose_restart.yaml @@ -1,6 +1,16 @@ command: docker compose restart short: Restart containers -long: Restart containers +long: |- + Restarts all stopped and running services. + + If you make changes to your `compose.yml` configuration, these changes are not reflected + after running this command. For example, changes to environment variables (which are added + after a container is built, but before the container's command is executed) are not updated + after restarting. + + If you are looking to configure a service's restart policy, please refer to + [restart](https://github.com/compose-spec/compose-spec/blob/master/spec.md#restart) + or [restart_policy](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#restart_policy). usage: docker compose restart pname: docker compose plink: docker_compose.yaml diff --git a/docs/yaml/main/generate.go b/docs/yaml/main/generate.go index 72f500e78..3358a2328 100644 --- a/docs/yaml/main/generate.go +++ b/docs/yaml/main/generate.go @@ -26,7 +26,7 @@ import ( "github.com/spf13/cobra" ) -func generateCliYaml(opts *options) error { +func generateDocs(opts *options) error { cmd := &cobra.Command{ Use: "docker", DisableAutoGenTag: true, @@ -43,7 +43,7 @@ func generateCliYaml(opts *options) error { if err != nil { return err } - return tool.GenYamlTree(cmd) + return tool.GenAllTree() } func disableFlagsInUseLine(cmd *cobra.Command) { @@ -76,7 +76,7 @@ func main() { } fmt.Printf("Project root: %s\n", opts.source) fmt.Printf("Generating yaml files into %s\n", opts.target) - if err := generateCliYaml(opts); err != nil { + if err := generateDocs(opts); err != nil { _, _ = fmt.Fprintf(os.Stderr, "Failed to generate documentation: %s\n", err.Error()) } }