1
0
Эх сурвалжийг харах

update docs generation to avoid man pages generation

Signed-off-by: Guillaume Lours <[email protected]>
Guillaume Lours 1 жил өмнө
parent
commit
231ea10058
34 өөрчлөгдсөн 519 нэмэгдсэн , 193 устгасан
  1. 147 4
      docs/reference/compose.md
  2. 2 2
      docs/reference/compose_alpha_publish.md
  3. 8 8
      docs/reference/compose_alpha_viz.md
  4. 2 2
      docs/reference/compose_attach.md
  5. 15 7
      docs/reference/compose_build.md
  6. 16 14
      docs/reference/compose_config.md
  7. 6 6
      docs/reference/compose_cp.md
  8. 7 7
      docs/reference/compose_create.md
  9. 16 4
      docs/reference/compose_down.md
  10. 23 5
      docs/reference/compose_events.md
  11. 7 4
      docs/reference/compose_exec.md
  12. 2 2
      docs/reference/compose_images.md
  13. 7 3
      docs/reference/compose_kill.md
  14. 6 6
      docs/reference/compose_logs.md
  15. 4 4
      docs/reference/compose_ls.md
  16. 4 4
      docs/reference/compose_pause.md
  17. 2 2
      docs/reference/compose_port.md
  18. 21 6
      docs/reference/compose_ps.md
  19. 6 6
      docs/reference/compose_pull.md
  20. 24 7
      docs/reference/compose_push.md
  21. 15 6
      docs/reference/compose_restart.md
  22. 19 10
      docs/reference/compose_rm.md
  23. 62 10
      docs/reference/compose_run.md
  24. 4 4
      docs/reference/compose_scale.md
  25. 4 4
      docs/reference/compose_start.md
  26. 4 4
      docs/reference/compose_stats.md
  27. 5 5
      docs/reference/compose_stop.md
  28. 4 4
      docs/reference/compose_top.md
  29. 4 4
      docs/reference/compose_unpause.md
  30. 40 22
      docs/reference/compose_up.md
  31. 2 2
      docs/reference/compose_version.md
  32. 4 4
      docs/reference/compose_wait.md
  33. 6 6
      docs/reference/compose_watch.md
  34. 21 5
      docs/yaml/main/generate.go

+ 147 - 4
docs/reference/compose.md

@@ -1,7 +1,150 @@
 # docker compose
 # docker compose
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Define and run multi-container applications with Docker
+You can use the compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
+multiple services in Docker containers.
+
+### Use `-f` to specify the name and path of one or more Compose files
+Use the `-f` flag to specify the location of a Compose configuration file.
+
+#### Specifying multiple Compose files
+You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
+configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
+to their predecessors.
+
+For example, consider this command line:
+
+```console
+$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db
+```
+
+The `docker-compose.yml` file might specify a `webapp` service.
+
+```yaml
+services:
+  webapp:
+    image: examples/web
+    ports:
+      - "8000:8000"
+    volumes:
+      - "/data"
+```
+If the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file.
+New values, add to the `webapp` service configuration.
+
+```yaml
+services:
+  webapp:
+    build: .
+    environment:
+      - DEBUG=1
+```
+
+When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
+with `-f`. You can use the `--project-directory` option to override this base path.
+
+Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
+configuration are relative to the current working directory.
+
+The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
+and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.
+
+#### Specifying a path to a single Compose file
+You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
+from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.
+
+For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and
+have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to
+get the postgres image for the db service from anywhere by using the `-f` flag as follows:
+
+```console
+$ docker compose -f ~/sandbox/rails/compose.yaml pull db
+```
+
+### Use `-p` to specify a project name
+
+Each configuration has a project name. Compose sets the project name using
+the following mechanisms, in order of precedence:
+- The `-p` command line flag
+- The `COMPOSE_PROJECT_NAME` environment variable
+- The top level `name:` variable from the config file (or the last `name:`
+from a series of config files specified using `-f`)
+- The `basename` of the project directory containing the config file (or
+containing the first config file specified using `-f`)
+- The `basename` of the current directory if no config file is specified
+Project names must contain only lowercase letters, decimal digits, dashes,
+and underscores, and must begin with a lowercase letter or decimal digit. If
+the `basename` of the project directory or current directory violates this
+constraint, you must use one of the other mechanisms.
+
+```console
+$ docker compose -p my_project ps -a
+NAME                 SERVICE    STATUS     PORTS
+my_project_demo_1    demo       running
+
+$ docker compose -p my_project logs
+demo_1  | PING localhost (127.0.0.1): 56 data bytes
+demo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
+```
+
+### Use profiles to enable optional services
+
+Use `--profile` to specify one or more active profiles
+Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services
+without any specified profiles.
+You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled.
+
+Profiles can also be set by `COMPOSE_PROFILES` environment variable.
+
+### Configuring parallelism
+
+Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
+Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
+one at a time. This can also be used to control build concurrency.
+
+Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
+
+### Set up environment variables
+
+You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
+
+Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
+`COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
+`COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag
+and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.
+
+If flags are explicitly set on the command line, the associated environment variable is ignored.
+
+Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops docker compose from detecting orphaned
+containers for the project.
+
+Setting the `COMPOSE_MENU` environment variable to `false` disables the helper menu when running `docker compose up`
+in attached mode. Alternatively, you can also run `docker compose up --menu=false` to disable the helper menu.
+
+### Use Dry Run mode to test your command
+
+Use `--dry-run` flag to test a command without changing your application stack state.
+Dry Run mode shows you all the steps Compose applies when executing a command, for example:
+```console
+$ docker compose --dry-run up --build -d
+[+] Pulling 1/1
+ ✔ DRY-RUN MODE -  db Pulled                                                                                                                                                                                                               0.9s
+[+] Running 10/8
+ ✔ DRY-RUN MODE -    build service backend                                                                                                                                                                                                 0.0s
+ ✔ DRY-RUN MODE -  ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd                                                                                                                                                   0.0s
+ ✔ DRY-RUN MODE -  ==> ==> naming to nginx-golang-mysql-backend                                                                                                                                                                            0.0s
+ ✔ DRY-RUN MODE -  Network nginx-golang-mysql_default                                    Created                                                                                                                                           0.0s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Created                                                                                                                                           0.0s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Created                                                                                                                                           0.0s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Created                                                                                                                                           0.0s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Healthy                                                                                                                                           0.5s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
+ ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started
+```
+From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service.
+Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.
+
+Dry Run mode works with almost all commands. You cannot use Dry Run mode with a command that doesn't change the state of a Compose stack such as `ps`, `ls`, `logs` for example.
 
 
 ### Subcommands
 ### Subcommands
 
 
@@ -43,10 +186,10 @@ Define and run multi-container applications with Docker
 
 
 | Name                   | Type          | Default | Description                                                                                         |
 | Name                   | Type          | Default | Description                                                                                         |
 |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
 |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
-| `--all-resources`      |               |         | Include all resources, even those not used by services                                              |
+| `--all-resources`      | `bool`        |         | Include all resources, even those not used by services                                              |
 | `--ansi`               | `string`      | `auto`  | Control when to print ANSI control characters ("never"\|"always"\|"auto")                           |
 | `--ansi`               | `string`      | `auto`  | Control when to print ANSI control characters ("never"\|"always"\|"auto")                           |
-| `--compatibility`      |               |         | Run compose in backward compatibility mode                                                          |
-| `--dry-run`            |               |         | Execute command in dry run mode                                                                     |
+| `--compatibility`      | `bool`        |         | Run compose in backward compatibility mode                                                          |
+| `--dry-run`            | `bool`        |         | Execute command in dry run mode                                                                     |
 | `--env-file`           | `stringArray` |         | Specify an alternate environment file                                                               |
 | `--env-file`           | `stringArray` |         | Specify an alternate environment file                                                               |
 | `-f`, `--file`         | `stringArray` |         | Compose configuration files                                                                         |
 | `-f`, `--file`         | `stringArray` |         | Compose configuration files                                                                         |
 | `--parallel`           | `int`         | `-1`    | Control max parallelism, -1 for unlimited                                                           |
 | `--parallel`           | `int`         | `-1`    | Control max parallelism, -1 for unlimited                                                           |

+ 2 - 2
docs/reference/compose_alpha_publish.md

@@ -7,9 +7,9 @@ Publish compose application
 
 
 | Name                      | Type     | Default | Description                                                                    |
 | Name                      | Type     | Default | Description                                                                    |
 |:--------------------------|:---------|:--------|:-------------------------------------------------------------------------------|
 |:--------------------------|:---------|:--------|:-------------------------------------------------------------------------------|
-| `--dry-run`               |          |         | Execute command in dry run mode                                                |
+| `--dry-run`               | `bool`   |         | Execute command in dry run mode                                                |
 | `--oci-version`           | `string` |         | OCI Image/Artifact specification version (automatically determined by default) |
 | `--oci-version`           | `string` |         | OCI Image/Artifact specification version (automatically determined by default) |
-| `--resolve-image-digests` |          |         | Pin image tags to digests                                                      |
+| `--resolve-image-digests` | `bool`   |         | Pin image tags to digests                                                      |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 8 - 8
docs/reference/compose_alpha_viz.md

@@ -5,14 +5,14 @@ EXPERIMENTAL - Generate a graphviz graph from your compose file
 
 
 ### Options
 ### Options
 
 
-| Name                 | Type  | Default | Description                                                                                        |
-|:---------------------|:------|:--------|:---------------------------------------------------------------------------------------------------|
-| `--dry-run`          |       |         | Execute command in dry run mode                                                                    |
-| `--image`            |       |         | Include service's image name in output graph                                                       |
-| `--indentation-size` | `int` | `1`     | Number of tabs or spaces to use for indentation                                                    |
-| `--networks`         |       |         | Include service's attached networks in output graph                                                |
-| `--ports`            |       |         | Include service's exposed ports in output graph                                                    |
-| `--spaces`           |       |         | If given, space character ' ' will be used to indent,<br>otherwise tab character '\t' will be used |
+| Name                 | Type   | Default | Description                                                                                        |
+|:---------------------|:-------|:--------|:---------------------------------------------------------------------------------------------------|
+| `--dry-run`          | `bool` |         | Execute command in dry run mode                                                                    |
+| `--image`            | `bool` |         | Include service's image name in output graph                                                       |
+| `--indentation-size` | `int`  | `1`     | Number of tabs or spaces to use for indentation                                                    |
+| `--networks`         | `bool` |         | Include service's attached networks in output graph                                                |
+| `--ports`            | `bool` |         | Include service's exposed ports in output graph                                                    |
+| `--spaces`           | `bool` |         | If given, space character ' ' will be used to indent,<br>otherwise tab character '\t' will be used |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 2 - 2
docs/reference/compose_attach.md

@@ -8,9 +8,9 @@ Attach local standard input, output, and error streams to a service's running co
 | Name            | Type     | Default | Description                                               |
 | Name            | Type     | Default | Description                                               |
 |:----------------|:---------|:--------|:----------------------------------------------------------|
 |:----------------|:---------|:--------|:----------------------------------------------------------|
 | `--detach-keys` | `string` |         | Override the key sequence for detaching from a container. |
 | `--detach-keys` | `string` |         | Override the key sequence for detaching from a container. |
-| `--dry-run`     |          |         | Execute command in dry run mode                           |
+| `--dry-run`     | `bool`   |         | Execute command in dry run mode                           |
 | `--index`       | `int`    | `0`     | index of the container if service has multiple replicas.  |
 | `--index`       | `int`    | `0`     | index of the container if service has multiple replicas.  |
-| `--no-stdin`    |          |         | Do not attach STDIN                                       |
+| `--no-stdin`    | `bool`   |         | Do not attach STDIN                                       |
 | `--sig-proxy`   | `bool`   | `true`  | Proxy all received signals to the process                 |
 | `--sig-proxy`   | `bool`   | `true`  | Proxy all received signals to the process                 |
 
 
 
 

+ 15 - 7
docs/reference/compose_build.md

@@ -1,7 +1,15 @@
 # docker compose build
 # docker compose build
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Build or rebuild services
+Services are built once and then tagged, by default as `project-service`.
+
+If the Compose file specifies an
+[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name,
+the image is tagged with that name, substituting any variables beforehand. See
+[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).
+
+If you change a service's `Dockerfile` or the contents of its build directory,
+run `docker compose build` to rebuild it.
 
 
 ### Options
 ### Options
 
 
@@ -9,14 +17,14 @@ Build or rebuild services
 |:----------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------|
 |:----------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------|
 | `--build-arg`         | `stringArray` |         | Set build-time variables for services                                                                       |
 | `--build-arg`         | `stringArray` |         | Set build-time variables for services                                                                       |
 | `--builder`           | `string`      |         | Set builder to use                                                                                          |
 | `--builder`           | `string`      |         | Set builder to use                                                                                          |
-| `--dry-run`           |               |         | Execute command in dry run mode                                                                             |
+| `--dry-run`           | `bool`        |         | Execute command in dry run mode                                                                             |
 | `-m`, `--memory`      | `bytes`       | `0`     | Set memory limit for the build container. Not supported by BuildKit.                                        |
 | `-m`, `--memory`      | `bytes`       | `0`     | Set memory limit for the build container. Not supported by BuildKit.                                        |
-| `--no-cache`          |               |         | Do not use cache when building the image                                                                    |
-| `--pull`              |               |         | Always attempt to pull a newer version of the image                                                         |
-| `--push`              |               |         | Push service images                                                                                         |
-| `-q`, `--quiet`       |               |         | Don't print anything to STDOUT                                                                              |
+| `--no-cache`          | `bool`        |         | Do not use cache when building the image                                                                    |
+| `--pull`              | `bool`        |         | Always attempt to pull a newer version of the image                                                         |
+| `--push`              | `bool`        |         | Push service images                                                                                         |
+| `-q`, `--quiet`       | `bool`        |         | Don't print anything to STDOUT                                                                              |
 | `--ssh`               | `string`      |         | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) |
 | `--ssh`               | `string`      |         | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) |
-| `--with-dependencies` |               |         | Also build dependencies (transitively)                                                                      |
+| `--with-dependencies` | `bool`        |         | Also build dependencies (transitively)                                                                      |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 16 - 14
docs/reference/compose_config.md

@@ -1,7 +1,9 @@
 # docker compose convert
 # docker compose convert
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Parse, resolve and render compose file in canonical format
+`docker compose config` renders the actual data model to be applied on the Docker Engine.
+It merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
+the canonical format.
 
 
 ### Aliases
 ### Aliases
 
 
@@ -11,22 +13,22 @@ Parse, resolve and render compose file in canonical format
 
 
 | Name                      | Type     | Default | Description                                                                 |
 | Name                      | Type     | Default | Description                                                                 |
 |:--------------------------|:---------|:--------|:----------------------------------------------------------------------------|
 |:--------------------------|:---------|:--------|:----------------------------------------------------------------------------|
-| `--dry-run`               |          |         | Execute command in dry run mode                                             |
-| `--environment`           |          |         | Print environment used for interpolation.                                   |
+| `--dry-run`               | `bool`   |         | Execute command in dry run mode                                             |
+| `--environment`           | `bool`   |         | Print environment used for interpolation.                                   |
 | `--format`                | `string` | `yaml`  | Format the output. Values: [yaml \| json]                                   |
 | `--format`                | `string` | `yaml`  | Format the output. Values: [yaml \| json]                                   |
 | `--hash`                  | `string` |         | Print the service config hash, one per line.                                |
 | `--hash`                  | `string` |         | Print the service config hash, one per line.                                |
-| `--images`                |          |         | Print the image names, one per line.                                        |
-| `--no-consistency`        |          |         | Don't check model consistency - warning: may produce invalid Compose output |
-| `--no-interpolate`        |          |         | Don't interpolate environment variables                                     |
-| `--no-normalize`          |          |         | Don't normalize compose model                                               |
-| `--no-path-resolution`    |          |         | Don't resolve file paths                                                    |
+| `--images`                | `bool`   |         | Print the image names, one per line.                                        |
+| `--no-consistency`        | `bool`   |         | Don't check model consistency - warning: may produce invalid Compose output |
+| `--no-interpolate`        | `bool`   |         | Don't interpolate environment variables                                     |
+| `--no-normalize`          | `bool`   |         | Don't normalize compose model                                               |
+| `--no-path-resolution`    | `bool`   |         | Don't resolve file paths                                                    |
 | `-o`, `--output`          | `string` |         | Save to file (default to stdout)                                            |
 | `-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.                                      |
-| `--variables`             |          |         | Print model variables and default values.                                   |
-| `--volumes`               |          |         | Print the volume names, one per line.                                       |
+| `--profiles`              | `bool`   |         | Print the profile names, one per line.                                      |
+| `-q`, `--quiet`           | `bool`   |         | Only validate the configuration, don't print anything                       |
+| `--resolve-image-digests` | `bool`   |         | Pin image tags to digests                                                   |
+| `--services`              | `bool`   |         | Print the service names, one per line.                                      |
+| `--variables`             | `bool`   |         | Print model variables and default values.                                   |
+| `--volumes`               | `bool`   |         | Print the volume names, one per line.                                       |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 6 - 6
docs/reference/compose_cp.md

@@ -5,12 +5,12 @@ Copy files/folders between a service container and the local filesystem
 
 
 ### Options
 ### Options
 
 
-| Name                  | Type  | Default | Description                                             |
-|:----------------------|:------|:--------|:--------------------------------------------------------|
-| `-a`, `--archive`     |       |         | Archive mode (copy all uid/gid information)             |
-| `--dry-run`           |       |         | Execute command in dry run mode                         |
-| `-L`, `--follow-link` |       |         | Always follow symbol link in SRC_PATH                   |
-| `--index`             | `int` | `0`     | Index of the container if service has multiple replicas |
+| Name                  | Type   | Default | Description                                             |
+|:----------------------|:-------|:--------|:--------------------------------------------------------|
+| `-a`, `--archive`     | `bool` |         | Archive mode (copy all uid/gid information)             |
+| `--dry-run`           | `bool` |         | Execute command in dry run mode                         |
+| `-L`, `--follow-link` | `bool` |         | Always follow symbol link in SRC_PATH                   |
+| `--index`             | `int`  | `0`     | Index of the container if service has multiple replicas |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 7 - 7
docs/reference/compose_create.md

@@ -7,14 +7,14 @@ Creates containers for a service
 
 
 | Name               | Type          | Default  | Description                                                                                   |
 | Name               | Type          | Default  | Description                                                                                   |
 |:-------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------|
 |:-------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------|
-| `--build`          |               |          | Build images before starting containers                                                       |
-| `--dry-run`        |               |          | Execute command in dry run mode                                                               |
-| `--force-recreate` |               |          | Recreate containers even if their configuration and image haven't changed                     |
-| `--no-build`       |               |          | Don't build an image, even if it's policy                                                     |
-| `--no-recreate`    |               |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.         |
+| `--build`          | `bool`        |          | Build images before starting containers                                                       |
+| `--dry-run`        | `bool`        |          | Execute command in dry run mode                                                               |
+| `--force-recreate` | `bool`        |          | Recreate containers even if their configuration and image haven't changed                     |
+| `--no-build`       | `bool`        |          | Don't build an image, even if it's policy                                                     |
+| `--no-recreate`    | `bool`        |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.         |
 | `--pull`           | `string`      | `policy` | Pull image before running ("always"\|"missing"\|"never"\|"build")                             |
 | `--pull`           | `string`      | `policy` | Pull image before running ("always"\|"missing"\|"never"\|"build")                             |
-| `--quiet-pull`     |               |          | Pull without printing progress information                                                    |
-| `--remove-orphans` |               |          | Remove containers for services not defined in the Compose file                                |
+| `--quiet-pull`     | `bool`        |          | Pull without printing progress information                                                    |
+| `--remove-orphans` | `bool`        |          | Remove containers for services not defined in the Compose file                                |
 | `--scale`          | `stringArray` |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. |
 | `--scale`          | `stringArray` |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. |
 
 
 
 

+ 16 - 4
docs/reference/compose_down.md

@@ -1,17 +1,29 @@
 # docker compose down
 # docker compose down
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Stop and remove containers, networks
+Stops containers and removes containers, networks, volumes, and images created by `up`.
+
+By default, the only things removed are:
+
+- Containers for services defined in the Compose file.
+- Networks defined in the networks section of the Compose file.
+- The default network, if one is used.
+
+Networks and volumes defined as external are never removed.
+
+Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically
+mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
+named volumes.
 
 
 ### Options
 ### Options
 
 
 | Name               | Type     | Default | Description                                                                                                             |
 | Name               | Type     | Default | Description                                                                                                             |
 |:-------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------------|
 |:-------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------------|
-| `--dry-run`        |          |         | Execute command in dry run mode                                                                                         |
-| `--remove-orphans` |          |         | Remove containers for services not defined in the Compose file                                                          |
+| `--dry-run`        | `bool`   |         | Execute command in dry run mode                                                                                         |
+| `--remove-orphans` | `bool`   |         | 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")                |
 | `--rmi`            | `string` |         | Remove images used by services. "local" remove only images that don't have a custom tag ("local"\|"all")                |
 | `-t`, `--timeout`  | `int`    | `0`     | Specify a shutdown timeout in seconds                                                                                   |
 | `-t`, `--timeout`  | `int`    | `0`     | 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 |
+| `-v`, `--volumes`  | `bool`   |         | Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 23 - 5
docs/reference/compose_events.md

@@ -1,14 +1,32 @@
 # docker compose events
 # docker compose events
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Receive real time events from containers
+Stream container events for every container in the project.
+
+With the `--json` flag, a json object is printed one per line with the format:
+
+```json
+{
+    "time": "2015-11-20T18:01:03.615550",
+    "type": "container",
+    "action": "create",
+    "id": "213cf7...5fc39a",
+    "service": "web",
+    "attributes": {
+      "name": "application_web_1",
+      "image": "alpine:edge"
+    }
+}
+```
+
+The events that can be received using this can be seen [here](/reference/cli/docker/system/events/#object-types).
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                               |
-|:------------|:-----|:--------|:------------------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode           |
-| `--json`    |      |         | Output events as a stream of json objects |
+| Name        | Type   | Default | Description                               |
+|:------------|:-------|:--------|:------------------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode           |
+| `--json`    | `bool` |         | Output events as a stream of json objects |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 7 - 4
docs/reference/compose_exec.md

@@ -1,18 +1,21 @@
 # docker compose exec
 # docker compose exec
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Execute a command in a running container
+This is the equivalent of `docker exec` targeting a Compose service.
+
+With this subcommand, you can run arbitrary commands in your services. Commands allocate a TTY by default, so
+you can use a command such as `docker compose exec web sh` to get an interactive prompt.
 
 
 ### Options
 ### Options
 
 
 | Name              | Type          | Default | Description                                                                      |
 | Name              | Type          | Default | Description                                                                      |
 |:------------------|:--------------|:--------|:---------------------------------------------------------------------------------|
 |:------------------|:--------------|:--------|:---------------------------------------------------------------------------------|
-| `-d`, `--detach`  |               |         | Detached mode: Run command in the background                                     |
-| `--dry-run`       |               |         | Execute command in dry run mode                                                  |
+| `-d`, `--detach`  | `bool`        |         | Detached mode: Run command in the background                                     |
+| `--dry-run`       | `bool`        |         | Execute command in dry run mode                                                  |
 | `-e`, `--env`     | `stringArray` |         | Set environment variables                                                        |
 | `-e`, `--env`     | `stringArray` |         | Set environment variables                                                        |
 | `--index`         | `int`         | `0`     | Index of the container if service has multiple replicas                          |
 | `--index`         | `int`         | `0`     | Index of the container if service has multiple replicas                          |
 | `-T`, `--no-TTY`  | `bool`        | `true`  | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. |
 | `-T`, `--no-TTY`  | `bool`        | `true`  | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. |
-| `--privileged`    |               |         | Give extended privileges to the process                                          |
+| `--privileged`    | `bool`        |         | Give extended privileges to the process                                          |
 | `-u`, `--user`    | `string`      |         | Run the command as this user                                                     |
 | `-u`, `--user`    | `string`      |         | Run the command as this user                                                     |
 | `-w`, `--workdir` | `string`      |         | Path to workdir directory for this command                                       |
 | `-w`, `--workdir` | `string`      |         | Path to workdir directory for this command                                       |
 
 

+ 2 - 2
docs/reference/compose_images.md

@@ -7,9 +7,9 @@ List images used by the created containers
 
 
 | Name            | Type     | Default | Description                                |
 | Name            | Type     | Default | Description                                |
 |:----------------|:---------|:--------|:-------------------------------------------|
 |:----------------|:---------|:--------|:-------------------------------------------|
-| `--dry-run`     |          |         | Execute command in dry run mode            |
+| `--dry-run`     | `bool`   |         | Execute command in dry run mode            |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json] |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json] |
-| `-q`, `--quiet` |          |         | Only display IDs                           |
+| `-q`, `--quiet` | `bool`   |         | Only display IDs                           |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 7 - 3
docs/reference/compose_kill.md

@@ -1,14 +1,18 @@
 # docker compose kill
 # docker compose kill
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Force stop service containers
+Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example:
+
+```console
+$ docker-compose kill -s SIGINT
+```
 
 
 ### Options
 ### Options
 
 
 | Name               | Type     | Default   | Description                                                    |
 | Name               | Type     | Default   | Description                                                    |
 |:-------------------|:---------|:----------|:---------------------------------------------------------------|
 |:-------------------|:---------|:----------|:---------------------------------------------------------------|
-| `--dry-run`        |          |           | Execute command in dry run mode                                |
-| `--remove-orphans` |          |           | Remove containers for services not defined in the Compose file |
+| `--dry-run`        | `bool`   |           | Execute command in dry run mode                                |
+| `--remove-orphans` | `bool`   |           | Remove containers for services not defined in the Compose file |
 | `-s`, `--signal`   | `string` | `SIGKILL` | SIGNAL to send to the container                                |
 | `-s`, `--signal`   | `string` | `SIGKILL` | SIGNAL to send to the container                                |
 
 
 
 

+ 6 - 6
docs/reference/compose_logs.md

@@ -1,20 +1,20 @@
 # docker compose logs
 # docker compose logs
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-View output from containers
+Displays log output from services
 
 
 ### Options
 ### Options
 
 
 | Name                 | Type     | Default | Description                                                                                    |
 | Name                 | Type     | Default | Description                                                                                    |
 |:---------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
 |:---------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
-| `--dry-run`          |          |         | Execute command in dry run mode                                                                |
-| `-f`, `--follow`     |          |         | Follow log output                                                                              |
+| `--dry-run`          | `bool`   |         | Execute command in dry run mode                                                                |
+| `-f`, `--follow`     | `bool`   |         | Follow log output                                                                              |
 | `--index`            | `int`    | `0`     | index of the container if service has multiple replicas                                        |
 | `--index`            | `int`    | `0`     | index of the container if service has multiple replicas                                        |
-| `--no-color`         |          |         | Produce monochrome output                                                                      |
-| `--no-log-prefix`    |          |         | Don't print prefix in logs                                                                     |
+| `--no-color`         | `bool`   |         | Produce monochrome output                                                                      |
+| `--no-log-prefix`    | `bool`   |         | 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)    |
 | `--since`            | `string` |         | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)    |
 | `-n`, `--tail`       | `string` | `all`   | Number of lines to show from the end of the logs for each container                            |
 | `-n`, `--tail`       | `string` | `all`   | Number of lines to show from the end of the logs for each container                            |
-| `-t`, `--timestamps` |          |         | Show timestamps                                                                                |
+| `-t`, `--timestamps` | `bool`   |         | Show timestamps                                                                                |
 | `--until`            | `string` |         | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) |
 | `--until`            | `string` |         | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) |
 
 
 
 

+ 4 - 4
docs/reference/compose_ls.md

@@ -1,17 +1,17 @@
 # docker compose ls
 # docker compose ls
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-List running compose projects
+Lists running Compose projects
 
 
 ### Options
 ### Options
 
 
 | Name            | Type     | Default | Description                                |
 | Name            | Type     | Default | Description                                |
 |:----------------|:---------|:--------|:-------------------------------------------|
 |:----------------|:---------|:--------|:-------------------------------------------|
-| `-a`, `--all`   |          |         | Show all stopped Compose projects          |
-| `--dry-run`     |          |         | Execute command in dry run mode            |
+| `-a`, `--all`   | `bool`   |         | Show all stopped Compose projects          |
+| `--dry-run`     | `bool`   |         | Execute command in dry run mode            |
 | `--filter`      | `filter` |         | Filter output based on conditions provided |
 | `--filter`      | `filter` |         | Filter output based on conditions provided |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json] |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json] |
-| `-q`, `--quiet` |          |         | Only display IDs                           |
+| `-q`, `--quiet` | `bool`   |         | Only display IDs                           |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_pause.md

@@ -1,13 +1,13 @@
 # docker compose pause
 # docker compose pause
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Pause services
+Pauses running containers of a service. They can be unpaused with `docker compose unpause`.
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                     |
-|:------------|:-----|:--------|:--------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode |
+| Name        | Type   | Default | Description                     |
+|:------------|:-------|:--------|:--------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 2 - 2
docs/reference/compose_port.md

@@ -1,13 +1,13 @@
 # docker compose port
 # docker compose port
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Print the public port for a port binding
+Prints the public port for a port binding
 
 
 ### Options
 ### Options
 
 
 | Name         | Type     | Default | Description                                             |
 | Name         | Type     | Default | Description                                             |
 |:-------------|:---------|:--------|:--------------------------------------------------------|
 |:-------------|:---------|:--------|:--------------------------------------------------------|
-| `--dry-run`  |          |         | Execute command in dry run mode                         |
+| `--dry-run`  | `bool`   |         | Execute command in dry run mode                         |
 | `--index`    | `int`    | `0`     | Index of the container if service has multiple replicas |
 | `--index`    | `int`    | `0`     | Index of the container if service has multiple replicas |
 | `--protocol` | `string` | `tcp`   | tcp or udp                                              |
 | `--protocol` | `string` | `tcp`   | tcp or udp                                              |
 
 

+ 21 - 6
docs/reference/compose_ps.md

@@ -1,20 +1,35 @@
 # docker compose ps
 # docker compose ps
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-List containers
+Lists containers for a Compose project, with current status and exposed ports.
+
+```console
+$ docker compose ps
+NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
+example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
+```
+
+By default, only running containers are shown. `--all` flag can be used to include stopped containers.
+
+```console
+$ docker compose ps --all
+NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
+example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
+example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
+```
 
 
 ### Options
 ### Options
 
 
 | Name                  | Type          | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | Name                  | Type          | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                          |
 |:----------------------|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 |:----------------------|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `-a`, `--all`         |               |         | Show all stopped containers (including those created by the run command)                                                                                                                                                                                                                                                                                                                                                             |
-| `--dry-run`           |               |         | Execute command in dry run mode                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `-a`, `--all`         | `bool`        |         | Show all stopped containers (including those created by the run command)                                                                                                                                                                                                                                                                                                                                                             |
+| `--dry-run`           | `bool`        |         | Execute command in dry run mode                                                                                                                                                                                                                                                                                                                                                                                                      |
 | [`--filter`](#filter) | `string`      |         | Filter services by a property (supported filters: status)                                                                                                                                                                                                                                                                                                                                                                            |
 | [`--filter`](#filter) | `string`      |         | Filter services by a property (supported filters: status)                                                                                                                                                                                                                                                                                                                                                                            |
 | [`--format`](#format) | `string`      | `table` | Format output using a custom template:<br>'table':            Print output in table format with column headers (default)<br>'table TEMPLATE':   Print output in table format using the given Go template<br>'json':             Print in JSON format<br>'TEMPLATE':         Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
 | [`--format`](#format) | `string`      | `table` | Format output using a custom template:<br>'table':            Print output in table format with column headers (default)<br>'table TEMPLATE':   Print output in table format using the given Go template<br>'json':             Print in JSON format<br>'TEMPLATE':         Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
-| `--no-trunc`          |               |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `--no-trunc`          | `bool`        |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `--orphans`           | `bool`        | `true`  | Include orphaned services (not declared by project)                                                                                                                                                                                                                                                                                                                                                                                  |
 | `--orphans`           | `bool`        | `true`  | Include orphaned services (not declared by project)                                                                                                                                                                                                                                                                                                                                                                                  |
-| `-q`, `--quiet`       |               |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--services`          |               |         | Display services                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `-q`, `--quiet`       | `bool`        |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--services`          | `bool`        |         | Display services                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | [`--status`](#status) | `stringArray` |         | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited]                                                                                                                                                                                                                                                                                                                        |
 | [`--status`](#status) | `stringArray` |         | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited]                                                                                                                                                                                                                                                                                                                        |
 
 
 
 

+ 6 - 6
docs/reference/compose_pull.md

@@ -1,18 +1,18 @@
 # docker compose pull
 # docker compose pull
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Pull service images
+Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on those images
 
 
 ### Options
 ### Options
 
 
 | Name                     | Type     | Default | Description                                            |
 | Name                     | Type     | Default | Description                                            |
 |:-------------------------|:---------|:--------|:-------------------------------------------------------|
 |:-------------------------|:---------|:--------|:-------------------------------------------------------|
-| `--dry-run`              |          |         | Execute command in dry run mode                        |
-| `--ignore-buildable`     |          |         | Ignore images that can be built                        |
-| `--ignore-pull-failures` |          |         | Pull what it can and ignores images with pull failures |
-| `--include-deps`         |          |         | Also pull services declared as dependencies            |
+| `--dry-run`              | `bool`   |         | Execute command in dry run mode                        |
+| `--ignore-buildable`     | `bool`   |         | Ignore images that can be built                        |
+| `--ignore-pull-failures` | `bool`   |         | Pull what it can and ignores images with pull failures |
+| `--include-deps`         | `bool`   |         | Also pull services declared as dependencies            |
 | `--policy`               | `string` |         | Apply pull policy ("missing"\|"always")                |
 | `--policy`               | `string` |         | Apply pull policy ("missing"\|"always")                |
-| `-q`, `--quiet`          |          |         | Pull without printing progress information             |
+| `-q`, `--quiet`          | `bool`   |         | Pull without printing progress information             |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 24 - 7
docs/reference/compose_push.md

@@ -1,16 +1,33 @@
 # docker compose push
 # docker compose push
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Push service images
+Pushes images for services to their respective registry/repository.
+
+The following assumptions are made:
+- You are pushing an image you have built locally
+- You have access to the build key
+
+Examples
+
+```yaml
+services:
+  service1:
+    build: .
+    image: localhost:5000/yourimage  ## goes to local registry
+
+  service2:
+    build: .
+    image: your-dockerid/yourimage  ## goes to your repository on Docker Hub
+```
 
 
 ### Options
 ### Options
 
 
-| Name                     | Type | Default | Description                                            |
-|:-------------------------|:-----|:--------|:-------------------------------------------------------|
-| `--dry-run`              |      |         | Execute command in dry run mode                        |
-| `--ignore-push-failures` |      |         | Push what it can and ignores images with push failures |
-| `--include-deps`         |      |         | Also push images of services declared as dependencies  |
-| `-q`, `--quiet`          |      |         | Push without printing progress information             |
+| Name                     | Type   | Default | Description                                            |
+|:-------------------------|:-------|:--------|:-------------------------------------------------------|
+| `--dry-run`              | `bool` |         | Execute command in dry run mode                        |
+| `--ignore-push-failures` | `bool` |         | Push what it can and ignores images with push failures |
+| `--include-deps`         | `bool` |         | Also push images of services declared as dependencies  |
+| `-q`, `--quiet`          | `bool` |         | Push without printing progress information             |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 15 - 6
docs/reference/compose_restart.md

@@ -1,15 +1,24 @@
 # docker compose restart
 # docker compose restart
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Restart service containers
+Restarts all stopped and running services, or the specified services only.
+
+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, 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).
 
 
 ### Options
 ### Options
 
 
-| Name              | Type  | Default | Description                           |
-|:------------------|:------|:--------|:--------------------------------------|
-| `--dry-run`       |       |         | Execute command in dry run mode       |
-| `--no-deps`       |       |         | Don't restart dependent services      |
-| `-t`, `--timeout` | `int` | `0`     | Specify a shutdown timeout in seconds |
+| Name              | Type   | Default | Description                           |
+|:------------------|:-------|:--------|:--------------------------------------|
+| `--dry-run`       | `bool` |         | Execute command in dry run mode       |
+| `--no-deps`       | `bool` |         | Don't restart dependent services      |
+| `-t`, `--timeout` | `int`  | `0`     | Specify a shutdown timeout in seconds |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 19 - 10
docs/reference/compose_rm.md

@@ -1,21 +1,30 @@
 # docker compose rm
 # docker compose rm
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Removes stopped service containers
+Removes stopped service containers.
+
+By default, anonymous volumes attached to containers are not removed. You can override this with `-v`. To list all
+volumes, use `docker volume ls`.
 
 
-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 is lost.
+
+Running the command with no options also removes one-off containers created by `docker compose run`:
 
 
-Any data which is not in a volume will be lost.
+```console
+$ docker compose rm
+Going to remove djangoquickstart_web_run_1
+Are you sure? [yN] y
+Removing djangoquickstart_web_run_1 ... done
+```
 
 
 ### Options
 ### Options
 
 
-| Name              | Type | Default | Description                                         |
-|:------------------|:-----|:--------|:----------------------------------------------------|
-| `--dry-run`       |      |         | Execute command in dry run mode                     |
-| `-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 |
+| Name              | Type   | Default | Description                                         |
+|:------------------|:-------|:--------|:----------------------------------------------------|
+| `--dry-run`       | `bool` |         | Execute command in dry run mode                     |
+| `-f`, `--force`   | `bool` |         | Don't ask to confirm removal                        |
+| `-s`, `--stop`    | `bool` |         | Stop the containers, if required, before removing   |
+| `-v`, `--volumes` | `bool` |         | Remove any anonymous volumes attached to containers |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 62 - 10
docs/reference/compose_run.md

@@ -1,30 +1,82 @@
 # docker compose run
 # docker compose run
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Run a one-off command on a service
+Runs a one-time command against a service.
+
+The following command starts the `web` service and runs `bash` as its command:
+
+```console
+$ docker compose run web bash
+```
+
+Commands you use with run start in new containers with configuration defined by that of the service,
+including volumes, links, and other details. However, there are two important differences:
+
+First, the command passed by `run` overrides the command defined in the service configuration. For example, if the
+`web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with
+`python app.py`.
+
+The second difference is that the `docker compose run` command does not create any of the ports specified in the
+service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports
+to be created and mapped to the host, specify the `--service-ports`
+
+```console
+$ docker compose run --service-ports web python manage.py shell
+```
+
+Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:
+
+```console
+$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
+```
+
+If you start a service configured with links, the run command first checks to see if the linked service is running
+and starts the service if it is stopped. Once all the linked services are running, the run executes the command you
+passed it. For example, you could run:
+
+```console
+$ docker compose run db psql -h db -U docker
+```
+
+This opens an interactive PostgreSQL shell for the linked `db` container.
+
+If you do not want the run command to start linked containers, use the `--no-deps` flag:
+
+```console
+$ docker compose run --no-deps web python manage.py shell
+```
+
+If you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:
+
+```console
+$ docker compose run --rm web python manage.py db upgrade
+```
+
+This runs a database upgrade script, and removes the container when finished running, even if a restart policy is
+specified in the service configuration.
 
 
 ### Options
 ### Options
 
 
 | Name                    | Type          | Default | Description                                                                      |
 | Name                    | Type          | Default | Description                                                                      |
 |:------------------------|:--------------|:--------|:---------------------------------------------------------------------------------|
 |:------------------------|:--------------|:--------|:---------------------------------------------------------------------------------|
-| `--build`               |               |         | Build image before starting container                                            |
+| `--build`               | `bool`        |         | Build image before starting container                                            |
 | `--cap-add`             | `list`        |         | Add Linux capabilities                                                           |
 | `--cap-add`             | `list`        |         | Add Linux capabilities                                                           |
 | `--cap-drop`            | `list`        |         | Drop Linux capabilities                                                          |
 | `--cap-drop`            | `list`        |         | Drop Linux capabilities                                                          |
-| `-d`, `--detach`        |               |         | Run container in background and print container ID                               |
-| `--dry-run`             |               |         | Execute command in dry run mode                                                  |
+| `-d`, `--detach`        | `bool`        |         | Run container in background and print container ID                               |
+| `--dry-run`             | `bool`        |         | Execute command in dry run mode                                                  |
 | `--entrypoint`          | `string`      |         | Override the entrypoint of the image                                             |
 | `--entrypoint`          | `string`      |         | Override the entrypoint of the image                                             |
 | `-e`, `--env`           | `stringArray` |         | Set environment variables                                                        |
 | `-e`, `--env`           | `stringArray` |         | Set environment variables                                                        |
 | `-i`, `--interactive`   | `bool`        | `true`  | Keep STDIN open even if not attached                                             |
 | `-i`, `--interactive`   | `bool`        | `true`  | Keep STDIN open even if not attached                                             |
 | `-l`, `--label`         | `stringArray` |         | Add or override a label                                                          |
 | `-l`, `--label`         | `stringArray` |         | Add or override a label                                                          |
 | `--name`                | `string`      |         | Assign a name to the container                                                   |
 | `--name`                | `string`      |         | Assign a name to the container                                                   |
 | `-T`, `--no-TTY`        | `bool`        | `true`  | Disable pseudo-TTY allocation (default: auto-detected)                           |
 | `-T`, `--no-TTY`        | `bool`        | `true`  | Disable pseudo-TTY allocation (default: auto-detected)                           |
-| `--no-deps`             |               |         | Don't start linked services                                                      |
+| `--no-deps`             | `bool`        |         | Don't start linked services                                                      |
 | `-p`, `--publish`       | `stringArray` |         | Publish a container's port(s) to the host                                        |
 | `-p`, `--publish`       | `stringArray` |         | Publish a container's port(s) to the host                                        |
-| `--quiet-pull`          |               |         | Pull without printing progress information                                       |
-| `--remove-orphans`      |               |         | Remove containers for services not defined in the Compose file                   |
-| `--rm`                  |               |         | Automatically remove the container when it exits                                 |
-| `-P`, `--service-ports` |               |         | Run command with all 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 |
+| `--quiet-pull`          | `bool`        |         | Pull without printing progress information                                       |
+| `--remove-orphans`      | `bool`        |         | Remove containers for services not defined in the Compose file                   |
+| `--rm`                  | `bool`        |         | Automatically remove the container when it exits                                 |
+| `-P`, `--service-ports` | `bool`        |         | Run command with all service's ports enabled and mapped to the host              |
+| `--use-aliases`         | `bool`        |         | Use the service's network useAliases in the network(s) the container connects to |
 | `-u`, `--user`          | `string`      |         | Run as specified username or uid                                                 |
 | `-u`, `--user`          | `string`      |         | Run as specified username or uid                                                 |
 | `-v`, `--volume`        | `stringArray` |         | Bind mount a volume                                                              |
 | `-v`, `--volume`        | `stringArray` |         | Bind mount a volume                                                              |
 | `-w`, `--workdir`       | `string`      |         | Working directory inside the container                                           |
 | `-w`, `--workdir`       | `string`      |         | Working directory inside the container                                           |

+ 4 - 4
docs/reference/compose_scale.md

@@ -5,10 +5,10 @@ Scale services
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                     |
-|:------------|:-----|:--------|:--------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode |
-| `--no-deps` |      |         | Don't start linked services     |
+| Name        | Type   | Default | Description                     |
+|:------------|:-------|:--------|:--------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode |
+| `--no-deps` | `bool` |         | Don't start linked services     |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_start.md

@@ -1,13 +1,13 @@
 # docker compose start
 # docker compose start
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Start services
+Starts existing containers for a service
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                     |
-|:------------|:-----|:--------|:--------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode |
+| Name        | Type   | Default | Description                     |
+|:------------|:-------|:--------|:--------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_stats.md

@@ -7,11 +7,11 @@ Display a live stream of container(s) resource usage statistics
 
 
 | Name          | Type     | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | Name          | Type     | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                          |
 |:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 |:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `-a`, `--all` |          |         | Show all containers (default shows just running)                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--dry-run`   |          |         | Execute command in dry run mode                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `-a`, `--all` | `bool`   |         | Show all containers (default shows just running)                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--dry-run`   | `bool`   |         | Execute command in dry run mode                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `--format`    | `string` |         | Format output using a custom template:<br>'table':            Print output in table format with column headers (default)<br>'table TEMPLATE':   Print output in table format using the given Go template<br>'json':             Print in JSON format<br>'TEMPLATE':         Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
 | `--format`    | `string` |         | Format output using a custom template:<br>'table':            Print output in table format with column headers (default)<br>'table TEMPLATE':   Print output in table format using the given Go template<br>'json':             Print in JSON format<br>'TEMPLATE':         Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
-| `--no-stream` |          |         | Disable streaming stats and only pull the first result                                                                                                                                                                                                                                                                                                                                                                               |
-| `--no-trunc`  |          |         | Do not truncate output                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--no-stream` | `bool`   |         | Disable streaming stats and only pull the first result                                                                                                                                                                                                                                                                                                                                                                               |
+| `--no-trunc`  | `bool`   |         | Do not truncate output                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 5 - 5
docs/reference/compose_stop.md

@@ -1,14 +1,14 @@
 # docker compose stop
 # docker compose stop
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Stop services
+Stops running containers without removing them. They can be started again with `docker compose start`.
 
 
 ### Options
 ### Options
 
 
-| Name              | Type  | Default | Description                           |
-|:------------------|:------|:--------|:--------------------------------------|
-| `--dry-run`       |       |         | Execute command in dry run mode       |
-| `-t`, `--timeout` | `int` | `0`     | Specify a shutdown timeout in seconds |
+| Name              | Type   | Default | Description                           |
+|:------------------|:-------|:--------|:--------------------------------------|
+| `--dry-run`       | `bool` |         | Execute command in dry run mode       |
+| `-t`, `--timeout` | `int`  | `0`     | Specify a shutdown timeout in seconds |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_top.md

@@ -1,13 +1,13 @@
 # docker compose top
 # docker compose top
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Display the running processes
+Displays the running processes
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                     |
-|:------------|:-----|:--------|:--------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode |
+| Name        | Type   | Default | Description                     |
+|:------------|:-------|:--------|:--------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_unpause.md

@@ -1,13 +1,13 @@
 # docker compose unpause
 # docker compose unpause
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Unpause services
+Unpauses paused containers of a service
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                     |
-|:------------|:-----|:--------|:--------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode |
+| Name        | Type   | Default | Description                     |
+|:------------|:-------|:--------|:--------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 40 - 22
docs/reference/compose_up.md

@@ -1,40 +1,58 @@
 # docker compose up
 # docker compose up
 
 
 <!---MARKER_GEN_START-->
 <!---MARKER_GEN_START-->
-Create and start containers
+Builds, (re)creates, starts, and attaches to containers for a service.
+
+Unless they are already running, this command also starts any linked services.
+
+The `docker compose up` command aggregates the output of each container (like `docker compose logs --follow` does).
+One can optionally select a subset of services to attach to using `--attach` flag, or exclude some services using
+`--no-attach` to prevent output to be flooded by some verbose services.
+
+When the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the
+background and leaves them running.
+
+If there are existing containers for a service, and the service’s configuration or image was changed after the
+container’s creation, `docker compose up` picks up the changes by stopping and recreating the containers
+(preserving mounted volumes). To prevent Compose from picking up changes, use the `--no-recreate` flag.
+
+If you want to force Compose to stop and recreate all containers, use the `--force-recreate` flag.
+
+If the process encounters an error, the exit code for this command is `1`.
+If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`.
 
 
 ### Options
 ### Options
 
 
 | Name                           | Type          | Default  | Description                                                                                                                                         |
 | Name                           | Type          | Default  | Description                                                                                                                                         |
 |:-------------------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
 |:-------------------------------|:--------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--abort-on-container-exit`    |               |          | Stops all containers if any container was stopped. Incompatible with -d                                                                             |
-| `--abort-on-container-failure` |               |          | Stops all containers if any container exited with failure. Incompatible with -d                                                                     |
-| `--always-recreate-deps`       |               |          | Recreate dependent containers. Incompatible with --no-recreate.                                                                                     |
+| `--abort-on-container-exit`    | `bool`        |          | Stops all containers if any container was stopped. Incompatible with -d                                                                             |
+| `--abort-on-container-failure` | `bool`        |          | Stops all containers if any container exited with failure. Incompatible with -d                                                                     |
+| `--always-recreate-deps`       | `bool`        |          | Recreate dependent containers. Incompatible with --no-recreate.                                                                                     |
 | `--attach`                     | `stringArray` |          | Restrict attaching to the specified services. Incompatible with --attach-dependencies.                                                              |
 | `--attach`                     | `stringArray` |          | Restrict attaching to the specified services. Incompatible with --attach-dependencies.                                                              |
-| `--attach-dependencies`        |               |          | Automatically attach to log output of dependent services                                                                                            |
-| `--build`                      |               |          | Build images before starting containers                                                                                                             |
-| `-d`, `--detach`               |               |          | Detached mode: Run containers in the background                                                                                                     |
-| `--dry-run`                    |               |          | Execute command in dry run mode                                                                                                                     |
+| `--attach-dependencies`        | `bool`        |          | Automatically attach to log output of dependent services                                                                                            |
+| `--build`                      | `bool`        |          | Build images before starting containers                                                                                                             |
+| `-d`, `--detach`               | `bool`        |          | Detached mode: Run containers in the background                                                                                                     |
+| `--dry-run`                    | `bool`        |          | Execute command in dry run mode                                                                                                                     |
 | `--exit-code-from`             | `string`      |          | Return the exit code of the selected service container. Implies --abort-on-container-exit                                                           |
 | `--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                                                                           |
-| `--menu`                       |               |          | Enable interactive shortcuts when running attached. Incompatible with --detach. Can also be enable/disable by setting COMPOSE_MENU environment var. |
+| `--force-recreate`             | `bool`        |          | Recreate containers even if their configuration and image haven't changed                                                                           |
+| `--menu`                       | `bool`        |          | Enable interactive shortcuts when running attached. Incompatible with --detach. Can also be enable/disable by setting COMPOSE_MENU environment var. |
 | `--no-attach`                  | `stringArray` |          | Do not attach (stream logs) to the specified services                                                                                               |
 | `--no-attach`                  | `stringArray` |          | Do not attach (stream logs) to the specified services                                                                                               |
-| `--no-build`                   |               |          | Don't build an image, even if it's policy                                                                                                           |
-| `--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                                                                                                        |
+| `--no-build`                   | `bool`        |          | Don't build an image, even if it's policy                                                                                                           |
+| `--no-color`                   | `bool`        |          | Produce monochrome output                                                                                                                           |
+| `--no-deps`                    | `bool`        |          | Don't start linked services                                                                                                                         |
+| `--no-log-prefix`              | `bool`        |          | Don't print prefix in logs                                                                                                                          |
+| `--no-recreate`                | `bool`        |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.                                                               |
+| `--no-start`                   | `bool`        |          | Don't start the services after creating them                                                                                                        |
 | `--pull`                       | `string`      | `policy` | Pull image before running ("always"\|"missing"\|"never")                                                                                            |
 | `--pull`                       | `string`      | `policy` | Pull image before running ("always"\|"missing"\|"never")                                                                                            |
-| `--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                                                                  |
+| `--quiet-pull`                 | `bool`        |          | Pull without printing progress information                                                                                                          |
+| `--remove-orphans`             | `bool`        |          | Remove containers for services not defined in the Compose file                                                                                      |
+| `-V`, `--renew-anon-volumes`   | `bool`        |          | 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.                                                       |
 | `--scale`                      | `stringArray` |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.                                                       |
 | `-t`, `--timeout`              | `int`         | `0`      | Use this timeout in seconds for container shutdown when attached or when containers are already running                                             |
 | `-t`, `--timeout`              | `int`         | `0`      | Use this timeout in seconds for container shutdown when attached or when containers are already running                                             |
-| `--timestamps`                 |               |          | Show timestamps                                                                                                                                     |
-| `--wait`                       |               |          | Wait for services to be running\|healthy. Implies detached mode.                                                                                    |
+| `--timestamps`                 | `bool`        |          | Show timestamps                                                                                                                                     |
+| `--wait`                       | `bool`        |          | Wait for services to be running\|healthy. Implies detached mode.                                                                                    |
 | `--wait-timeout`               | `int`         | `0`      | Maximum duration to wait for the project to be running\|healthy                                                                                     |
 | `--wait-timeout`               | `int`         | `0`      | Maximum duration to wait for the project to be running\|healthy                                                                                     |
-| `-w`, `--watch`                |               |          | Watch source code and rebuild/refresh containers when files are updated.                                                                            |
+| `-w`, `--watch`                | `bool`        |          | Watch source code and rebuild/refresh containers when files are updated.                                                                            |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 2 - 2
docs/reference/compose_version.md

@@ -7,9 +7,9 @@ Show the Docker Compose version information
 
 
 | Name             | Type     | Default | Description                                                    |
 | Name             | Type     | Default | Description                                                    |
 |:-----------------|:---------|:--------|:---------------------------------------------------------------|
 |:-----------------|:---------|:--------|:---------------------------------------------------------------|
-| `--dry-run`      |          |         | Execute command in dry run mode                                |
+| `--dry-run`      | `bool`   |         | Execute command in dry run mode                                |
 | `-f`, `--format` | `string` |         | Format the output. Values: [pretty \| json]. (Default: pretty) |
 | `-f`, `--format` | `string` |         | Format the output. Values: [pretty \| json]. (Default: pretty) |
-| `--short`        |          |         | Shows only Compose's version number                            |
+| `--short`        | `bool`   |         | Shows only Compose's version number                            |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 4 - 4
docs/reference/compose_wait.md

@@ -5,10 +5,10 @@ Block until the first service container stops
 
 
 ### Options
 ### Options
 
 
-| Name             | Type | Default | Description                                  |
-|:-----------------|:-----|:--------|:---------------------------------------------|
-| `--down-project` |      |         | Drops project when the first container stops |
-| `--dry-run`      |      |         | Execute command in dry run mode              |
+| Name             | Type   | Default | Description                                  |
+|:-----------------|:-------|:--------|:---------------------------------------------|
+| `--down-project` | `bool` |         | Drops project when the first container stops |
+| `--dry-run`      | `bool` |         | Execute command in dry run mode              |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 6 - 6
docs/reference/compose_watch.md

@@ -5,12 +5,12 @@ Watch build context for service and rebuild/refresh containers when files are up
 
 
 ### Options
 ### Options
 
 
-| Name        | Type | Default | Description                                   |
-|:------------|:-----|:--------|:----------------------------------------------|
-| `--dry-run` |      |         | Execute command in dry run mode               |
-| `--no-up`   |      |         | Do not build & start services before watching |
-| `--prune`   |      |         | Prune dangling images on rebuild              |
-| `--quiet`   |      |         | hide build output                             |
+| Name        | Type   | Default | Description                                   |
+|:------------|:-------|:--------|:----------------------------------------------|
+| `--dry-run` | `bool` |         | Execute command in dry run mode               |
+| `--no-up`   | `bool` |         | Do not build & start services before watching |
+| `--prune`   | `bool` |         | Prune dangling images on rebuild              |
+| `--quiet`   | `bool` |         | hide build output                             |
 
 
 
 
 <!---MARKER_GEN_END-->
 <!---MARKER_GEN_END-->

+ 21 - 5
docs/yaml/main/generate.go

@@ -48,7 +48,21 @@ func generateDocs(opts *options) error {
 	if err != nil {
 	if err != nil {
 		return err
 		return err
 	}
 	}
-	return tool.GenAllTree()
+	for _, format := range opts.formats {
+		switch format {
+		case "yaml":
+			if err := tool.GenYamlTree(cmd); err != nil {
+				return err
+			}
+		case "md":
+			if err := tool.GenMarkdownTree(cmd); err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("unknown format %q", format)
+		}
+	}
+	return nil
 }
 }
 
 
 func disableFlagsInUseLine(cmd *cobra.Command) {
 func disableFlagsInUseLine(cmd *cobra.Command) {
@@ -69,15 +83,17 @@ func visitAll(root *cobra.Command, fn func(*cobra.Command)) {
 }
 }
 
 
 type options struct {
 type options struct {
-	source string
-	target string
+	source  string
+	target  string
+	formats []string
 }
 }
 
 
 func main() {
 func main() {
 	cwd, _ := os.Getwd()
 	cwd, _ := os.Getwd()
 	opts := &options{
 	opts := &options{
-		source: filepath.Join(cwd, "docs", "reference"),
-		target: filepath.Join(cwd, "docs", "reference"),
+		source:  filepath.Join(cwd, "docs", "reference"),
+		target:  filepath.Join(cwd, "docs", "reference"),
+		formats: []string{"yaml", "md"},
 	}
 	}
 	fmt.Printf("Project root: %s\n", opts.source)
 	fmt.Printf("Project root: %s\n", opts.source)
 	fmt.Printf("Generating yaml files into %s\n", opts.target)
 	fmt.Printf("Generating yaml files into %s\n", opts.target)