docs: also generate "usage" in MarkDown files

Signed-off-by: Sebastiaan van Stijn <[email protected]>

docs/reference/compose.md

@@ -1,4 +1,54 @@
-
+# docker compose
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_build.md

@@ -1,3 +1,20 @@
+# docker compose build
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_convert.md

@@ -1,4 +1,30 @@
+# docker compose convert
 
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_cp.md

@@ -0,0 +1,17 @@
+# docker compose cp
+
+<!---MARKER_GEN_START-->
+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]. |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/compose_create.md

@@ -0,0 +1,17 @@
+# docker compose create
+
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/compose_down.md

@@ -1,4 +1,19 @@
+# docker compose down
 
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_events.md

@@ -1,3 +1,16 @@
+# docker compose events
+
+<!---MARKER_GEN_START-->
+Receive real time events from containers.
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--json` |  |  | Output events as a stream of json objects |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_exec.md

@@ -1,3 +1,22 @@
+# docker compose exec
+
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_images.md

@@ -0,0 +1,14 @@
+# docker compose images
+
+<!---MARKER_GEN_START-->
+List images used by the created containers
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-q`, `--quiet` |  |  | Only display IDs |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/compose_kill.md

@@ -1,3 +1,16 @@
+# docker compose kill
+
+<!---MARKER_GEN_START-->
+Force stop service containers.
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-s`, `--signal` | `string` | `SIGKILL` | SIGNAL to send to the container. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_logs.md

@@ -1,3 +1,22 @@
+# docker compose logs
+
+<!---MARKER_GEN_START-->
+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) |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_ls.md

@@ -1,3 +1,19 @@
+# docker compose ls
+
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_pause.md

@@ -1,3 +1,10 @@
+# docker compose pause
+
+<!---MARKER_GEN_START-->
+Pause services
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_port.md

@@ -1,3 +1,17 @@
+# docker compose port
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_ps.md

@@ -1,3 +1,20 @@
+# docker compose ps
+
+<!---MARKER_GEN_START-->
+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] |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_pull.md

@@ -1,3 +1,18 @@
+# docker compose pull
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_push.md

@@ -1,3 +1,16 @@
+# docker compose push
+
+<!---MARKER_GEN_START-->
+Push service images
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--ignore-push-failures` |  |  | Push what it can and ignores images with push failures |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_restart.md

@@ -1,3 +1,19 @@
+# docker compose restart
+
+<!---MARKER_GEN_START-->
+Restart containers
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-t`, `--timeout` | `int` | `10` | Specify a shutdown timeout in seconds |
+
+
+<!---MARKER_GEN_END-->
+
+## Description
+
 Restarts all stopped and running services.
 
 If you make changes to your `compose.yml` configuration, these changes are not reflected

docs/reference/compose_rm.md

@@ -1,3 +1,23 @@
+# docker compose rm
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_run.md

@@ -1,3 +1,31 @@
+# docker compose run
+
+<!---MARKER_GEN_START-->
+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 |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_start.md

@@ -1,3 +1,10 @@
+# docker compose start
+
+<!---MARKER_GEN_START-->
+Start services
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_stop.md

@@ -1,3 +1,16 @@
+# docker compose stop
+
+<!---MARKER_GEN_START-->
+Stop services
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `-t`, `--timeout` | `int` | `10` | Specify a shutdown timeout in seconds |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_top.md

@@ -1,3 +1,10 @@
+# docker compose top
+
+<!---MARKER_GEN_START-->
+Display the running processes
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_unpause.md

@@ -1,3 +1,10 @@
+# docker compose unpause
+
+<!---MARKER_GEN_START-->
+Unpause services
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_up.md

@@ -1,3 +1,35 @@
+# docker compose up
+
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

docs/reference/compose_version.md

@@ -0,0 +1,14 @@
+# docker compose version
+
+<!---MARKER_GEN_START-->
+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. |
+
+
+<!---MARKER_GEN_END-->

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

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())
 	}
 }