[v2] docs: regenerate yaml docs

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/docker_compose.yaml

@@ -1,56 +1,6 @@
 command: docker compose
 short: Docker Compose
-long: "You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND]
+long: "You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage\nmultiple services in Docker containers.\n\n### Use `-f` to specify name and path of one or more Compose files\nUse the `-f` flag to specify the location of a Compose configuration file.\n\n#### Specifying multiple Compose files\nYou can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single \nconfiguration. Compose builds the configuration in the order you supply the files. Subsequent files override and add \nto their predecessors.\n\nFor example, consider this command line:\n\n```\n$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db\n```\nThe `docker-compose.yml` file might specify a `webapp` service.\n\n```yaml\nservices:\n  webapp:\n    image: examples/web\n    ports:\n      - \"8000:8000\"\n    volumes:\n      - \"/data\"\n```\nIf the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file. \nNew values, add to the `webapp` service configuration.\n\n```yaml\nservices:\n  webapp:\n    build: .\n    environment:\n      - DEBUG=1\n```\n\nWhen you use multiple Compose files, all paths in the files are relative to the first configuration file specified \nwith `-f`. You can use the `--project-directory` option to override this base path.\n\nUse a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the \nconfiguration are relative to the current working directory.\n\nThe `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory \nand its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.\n\n#### Specifying a path to a single Compose file\nYou can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either \nfrom the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.\n\nFor an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and \nhave a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to \nget the postgres image for the db service from anywhere by using the `-f` flag as follows: \n```\ndocker compose -f ~/sandbox/rails/compose.yaml pull db\n```\n\n### Use `-p` to specify a project name\n\nEach configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t \nspecify the flag, Compose uses the current directory name. \nProject name can also be set by `COMPOSE_PROJECT_NAME` environment variable.\n\nMost compose subcommand can be ran without a compose file, just passing \nproject name to retrieve the relevant resources.\n\n```\n$ docker compose -p my_project ps -a\nNAME                 SERVICE    STATUS     PORTS\nmy_project_demo_1    demo       running             \n\n$ docker compose -p my_project logs\ndemo_1  | PING localhost (127.0.0.1): 56 data bytes\ndemo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms\n```\n\n### Use profiles to enable optional services\n\nUse `--profile` to specify one or more active profiles\nCalling `docker compose --profile frontend up` will start the services with the profile `frontend` and services \nwithout any specified profiles. \nYou can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.\n\nProfiles can also be set by `COMPOSE_PROFILES` environment variable.\n\n### Set up environment variables\n\nYou can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.\n\nSetting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,\n`COMPOSE_PROJECT_NAME` environment variable does the same for to the `-p` flag,\nand so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag.\n\nIf flags are explicitly set on command line, associated environment variable is ignored"
-    [ARGS...]`, to build and manage\nmultiple services in Docker containers.\n\n###
-    Use `-f` to specify name and path of one or more Compose files\nUse the `-f` flag
-    to specify the location of a Compose configuration file.\n\n#### Specifying multiple
-    Compose files\nYou can supply multiple `-f` configuration files. When you supply
-    multiple files, Compose combines them into a single \nconfiguration. Compose builds
-    the configuration in the order you supply the files. Subsequent files override
-    and add \nto their predecessors.\n\nFor example, consider this command line:\n\n```\n$
-    docker-compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db\n```\nThe
-    `docker-compose.yml` file might specify a `webapp` service.\n\n```yaml\nservices:\n
-    \ webapp:\n    image: examples/web\n    ports:\n      - \"8000:8000\"\n    volumes:\n
-    \     - \"/data\"\n```\nIf the `docker-compose.admin.yml` also specifies this
-    same service, any matching fields override the previous file. \nNew values, add
-    to the `webapp` service configuration.\n\n```yaml\nservices:\n  webapp:\n    build:
-    .\n    environment:\n      - DEBUG=1\n```\n\nWhen you use multiple Compose files,
-    all paths in the files are relative to the first configuration file specified
-    \nwith `-f`. You can use the `--project-directory` option to override this base
-    path.\n\nUse a `-f` with `-` (dash) as the filename to read the configuration
-    from stdin. When stdin is used all paths in the \nconfiguration are relative to
-    the current working directory.\n\nThe `-f` flag is optional. If you don’t provide
-    this flag on the command line, Compose traverses the working directory \nand its
-    parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.\n\n####
-    Specifying a path to a single Compose file\nYou can use the `-f` flag to specify
-    a path to a Compose file that is not located in the current directory, either
-    \nfrom the command line or by setting up a `COMPOSE_FILE` environment variable
-    in your shell or in an environment file.\n\nFor an example of using the `-f` option
-    at the command line, suppose you are running the Compose Rails sample, and \nhave
-    a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command
-    like `docker compose pull` to \nget the postgres image for the db service from
-    anywhere by using the `-f` flag as follows: \n```\ndocker compose -f ~/sandbox/rails/compose.yaml
-    pull db\n```\n\n### Use `-p` to specify a project name\n\nEach configuration has
-    a project name. If you supply a `-p` flag, you can specify a project name. If
-    you don’t \nspecify the flag, Compose uses the current directory name. \nProject
-    name can also be set by `COMPOSE_PROJECT_NAME` environment variable.\n\nMost compose
-    subcommand can be ran without a compose file, just passing \nproject name to retrieve
-    the relevant resources.\n\n```\n$ docker compose -p my_project ps -a\nNAME                 SERVICE
-    \   STATUS     PORTS\nmy_project_demo_1    demo       running             \n\n$
-    docker compose -p my_project logs\ndemo_1  | PING localhost (127.0.0.1): 56 data
-    bytes\ndemo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms\n```\n\n###
-    Use profiles to enable optional services\n\nUse `--profile` to specify one or
-    more active profiles\nCalling `docker compose --profile frontend up` will start
-    the services with the profile `frontend` and services \nwithout any specified
-    profiles. \nYou can also enable multiple profiles, e.g. with `docker compose --profile
-    frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.\n\nProfiles
-    can also be set by `COMPOSE_PROFILES` environment variable.\n\n### Set up environment
-    variables\n\nYou can set environment variables for various docker-compose options,
-    including the `-f`, `-p` and `--profiles` flags.\n\nSetting the `COMPOSE_FILE`
-    environment variable is equivalent to passing the `-f` flag,\n`COMPOSE_PROJECT_NAME`
-    environment variable does the same for to the `-p` flag,\nand so does `COMPOSE_PROFILES`
-    environment variable for to the `--profiles` flag.\n\nIf flags are explicitly
-    set on command line, associated environment variable is ignored"
 usage: docker compose
 pname: docker
 plink: docker.yaml
@@ -170,6 +120,15 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: verbose
+      value_type: bool
+      default_value: "false"
+      description: Show more output
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: workdir
       value_type: string
       description: |-

docs/reference/docker_compose_build.yaml

@@ -1,11 +1,6 @@
 command: docker compose build
 short: Build or rebuild services
-long: "Services are built once and then tagged, by default as `project_service`. \n\nIf
+long: "Services are built once and then tagged, by default as `project_service`. \n\nIf the Compose file specifies an\n[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name, \nthe image is tagged with that name, substituting any variables beforehand. See\n[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).\n\nIf you change a service's `Dockerfile` or the contents of its build directory, \nrun `docker compose build` to rebuild it."
-    the Compose file specifies an\n[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image)
-    name, \nthe image is tagged with that name, substituting any variables beforehand.
-    See\n[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).\n\nIf
-    you change a service's `Dockerfile` or the contents of its build directory, \nrun
-    `docker compose build` to rebuild it."
 usage: docker compose build [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_convert.yaml

@@ -1,11 +1,7 @@
 command: docker compose convert
 aliases: config
 short: Converts the compose file to platform's canonical format
-long: "`docker compose convert` render the actual data model to be applied on target
+long: "`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,\nit merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into \nfully defined Compose model. \n\nTo allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`"
-    platform. When used with Docker engine,\nit merges the Compose files set by `-f`
-    flags, resolves variables in Compose file, and expands short-notation into \nfully
-    defined Compose model. \n\nTo allow smooth migration from docker-compose, this
-    subcommand declares alias `docker compose config`"
 usage: docker compose convert SERVICES
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_exec.yaml

@@ -1,24 +1,10 @@
 command: docker compose exec
 short: Execute a command in a running container.
-long: "This is the equivalent of `docker exec` targeting a Compose service. \n\nWith
+long: "This is the equivalent of `docker exec` targeting a Compose service. \n\nWith this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so \nyou can use a command such as `docker compose exec web sh` to get an interactive prompt."
-    this subcommand you can run arbitrary commands in your services. Commands are
-    by default allocating a TTY, so \nyou can use a command such as `docker compose
-    exec web sh` to get an interactive prompt."
 usage: docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]
 pname: docker compose
 plink: docker_compose.yaml
 options:
-  - option: ""
-    shorthand: T
-    value_type: bool
-    default_value: "false"
-    description: |
-        Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.
-    deprecated: false
-    experimental: false
-    experimentalcli: false
-    kubernetes: false
-    swarm: false
     - option: detach
       shorthand: d
       value_type: bool
@@ -49,6 +35,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: no-TTY
+      shorthand: T
+      value_type: bool
+      default_value: "false"
+      description: |
+        Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: privileged
       value_type: bool
       default_value: "false"

docs/reference/docker_compose_logs.yaml

@@ -1,7 +1,7 @@
 command: docker compose logs
 short: View output from containers
 long: Displays log output from services.
-usage: docker compose logs [service...]
+usage: docker compose logs [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:
@@ -33,6 +33,25 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: since
+      value_type: string
+      description: |
+        Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: tail
+      value_type: string
+      default_value: all
+      description: |
+        Number of lines to show from the end of the logs for each container.
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: timestamps
       shorthand: t
       value_type: bool
@@ -43,6 +62,15 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: until
+      value_type: string
+      description: |
+        Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 experimental: false
 experimentalcli: false

docs/reference/docker_compose_ls.yaml

@@ -5,6 +5,16 @@ usage: docker compose ls
 pname: docker compose
 plink: docker_compose.yaml
 options:
+    - option: all
+      shorthand: a
+      value_type: bool
+      default_value: "false"
+      description: Show all stopped Compose projects
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: filter
       value_type: filter
       description: Filter output based on conditions provided.

docs/reference/docker_compose_pause.yaml

@@ -1,7 +1,6 @@
 command: docker compose pause
 short: pause services
-long: Pauses running containers of a service. They can be unpaused with `docker compose
+long: Pauses running containers of a service. They can be unpaused with `docker compose unpause`.
-    unpause`.
 usage: docker compose pause [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_ps.yaml

@@ -1,10 +1,7 @@
 command: docker compose ps
 short: List containers
-long: "Lists containers for a Compose project, with current status and exposed ports.\n\n```\n$
+long: "Lists containers for a Compose project, with current status and exposed ports.\n\n```\n$ docker compose ps\nNAME                SERVICE             STATUS              PORTS\nexample_foo_1       foo                 running (healthy)   0.0.0.0:8000->80/tcp\nexample_bar_1       bar                 exited (1)          \n```"
-    docker compose ps\nNAME                SERVICE             STATUS              PORTS\nexample_foo_1
+usage: docker compose ps [SERVICE...]
-    \      foo                 running (healthy)   0.0.0.0:8000->80/tcp\nexample_bar_1
-    \      bar                 exited (1)          \n```"
-usage: docker compose ps
 pname: docker compose
 plink: docker_compose.yaml
 options:
@@ -19,10 +16,18 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: filter
+      value_type: string
+      description: Filter services by a property
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: format
       value_type: string
       default_value: pretty
-    description: 'Format the output. Values: [pretty | json].'
+      description: 'Format the output. Values: [pretty | json]'
       deprecated: false
       experimental: false
       experimentalcli: false
@@ -47,6 +52,14 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: status
+      value_type: string
+      description: Filter services by status
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 experimental: false
 experimentalcli: false

docs/reference/docker_compose_pull.yaml

@@ -1,7 +1,6 @@
 command: docker compose pull
 short: Pull service images
-long: "Pulls an image associated with a service defined in a `compose.yaml` file,
+long: "Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on \nthose images."
-    but does not start containers based on \nthose images."
 usage: docker compose pull [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
@@ -52,29 +51,7 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-examples: "suppose you have this `compose.yaml` file from the Quickstart: [Compose
+examples: "suppose you have this `compose.yaml` file from the Quickstart: [Compose and Rails sample](compose/rails/).\n\n```yaml\nservices:\n  db:\n    image: postgres\n  web:\n    build: .\n    command: bundle exec rails s -p 3000 -b '0.0.0.0'\n    volumes:\n    - .:/myapp\n    ports:\n    - \"3000:3000\"\n    depends_on:\n    - db\n```\n\nIf you run `docker compose pull ServiceName` in the same directory as the `ccompose.yaml` file that defines the service, \nDocker pulls the associated image. For example, to call the postgres image configured as the db service in our example, \nyou would run `docker compose pull db`.\n\n```\n$ docker compose pull db\n[+] Running 1/15\n ⠸ db Pulling                                                             12.4s\n   ⠿ 45b42c59be33 Already exists                                           0.0s\n   ⠹ 40adec129f1a Downloading  3.374MB/4.178MB                             9.3s\n   ⠹ b4c431d00c78 Download complete                                        9.3s\n   ⠹ 2696974e2815 Download complete                                        9.3s\n   ⠹ 564b77596399 Downloading  5.622MB/7.965MB                             9.3s\n   ⠹ 5044045cf6f2 Downloading  216.7kB/391.1kB                             9.3s\n   ⠹ d736e67e6ac3 Waiting                                                  9.3s\n   ⠹ 390c1c9a5ae4 Waiting                                                  9.3s\n   ⠹ c0e62f172284 Waiting                                                  9.3s\n   ⠹ ebcdc659c5bf Waiting                                                  9.3s\n   ⠹ 29be22cb3acc Waiting                                                  9.3s\n   ⠹ f63c47038e66 Waiting                                                  9.3s\n   ⠹ 77a0c198cde5 Waiting                                                  9.3s\n   ⠹ c8752d5b785c Waiting                                                  9.3s\n``̀"
-    and Rails sample](compose/rails/).\n\n```yaml\nservices:\n  db:\n    image: postgres\n
-    \ web:\n    build: .\n    command: bundle exec rails s -p 3000 -b '0.0.0.0'\n
-    \   volumes:\n    - .:/myapp\n    ports:\n    - \"3000:3000\"\n    depends_on:\n
-    \   - db\n```\n\nIf you run `docker compose pull ServiceName` in the same directory
-    as the `ccompose.yaml` file that defines the service, \nDocker pulls the associated
-    image. For example, to call the postgres image configured as the db service in
-    our example, \nyou would run `docker compose pull db`.\n\n```\n$ docker compose
-    pull db\n[+] Running 1/15\n ⠸ db Pulling                                                             12.4s\n
-    \  ⠿ 45b42c59be33 Already exists                                           0.0s\n
-    \  ⠹ 40adec129f1a Downloading  3.374MB/4.178MB                             9.3s\n
-    \  ⠹ b4c431d00c78 Download complete                                        9.3s\n
-    \  ⠹ 2696974e2815 Download complete                                        9.3s\n
-    \  ⠹ 564b77596399 Downloading  5.622MB/7.965MB                             9.3s\n
-    \  ⠹ 5044045cf6f2 Downloading  216.7kB/391.1kB                             9.3s\n
-    \  ⠹ d736e67e6ac3 Waiting                                                  9.3s\n
-    \  ⠹ 390c1c9a5ae4 Waiting                                                  9.3s\n
-    \  ⠹ c0e62f172284 Waiting                                                  9.3s\n
-    \  ⠹ ebcdc659c5bf Waiting                                                  9.3s\n
-    \  ⠹ 29be22cb3acc Waiting                                                  9.3s\n
-    \  ⠹ f63c47038e66 Waiting                                                  9.3s\n
-    \  ⠹ 77a0c198cde5 Waiting                                                  9.3s\n
-    \  ⠹ c8752d5b785c Waiting                                                  9.3s\n``̀"
 deprecated: false
 experimental: false
 experimentalcli: false

docs/reference/docker_compose_push.yaml

@@ -1,11 +1,6 @@
 command: docker compose push
 short: Push service images
-long: "Pushes images for services to their respective registry/repository.\n\nThe
+long: "Pushes images for services to their respective registry/repository.\n\nThe following assumptions are made:\n- You are pushing an image you have built locally\n- You have access to the build key\n\nExamples\n\n```yaml\nservices:\n    service1:\n        build: .\n        image: localhost:5000/yourimage  ## goes to local registry\n    \n    service2:\n        build: .\n        image: your-dockerid/yourimage  ## goes to your repository on Docker Hub\n```"
-    following assumptions are made:\n- You are pushing an image you have built locally\n-
-    You have access to the build key\n\nExamples\n\n```yaml\nservices:\n    service1:\n
-    \       build: .\n        image: localhost:5000/yourimage  ## goes to local registry\n
-    \   \n    service2:\n        build: .\n        image: your-dockerid/yourimage
-    \ ## goes to your repository on Docker Hub\n```"
 usage: docker compose push [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_run.yaml

@@ -1,33 +1,7 @@
 command: docker compose run
 short: Run a one-off command on a service.
-long: "Runs a one-time command against a service. \n\nthe following command starts
+long: "Runs a one-time command against a service. \n\nthe following command starts the `web` service and runs `bash` as its command.\n`docker compose run web bash`\n\nCommands you use with run start in new containers with configuration defined by that of the service,\nincluding volumes, links, and other details. However, there are two important differences:\n\nFirst, the command passed by `run` overrides the command defined in the service configuration. For example, if the \n`web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with \n`python app.py`.\n\nThe second difference is that the `docker compose run` command does not create any of the ports specified in the \nservice configuration. This prevents port collisions with already-open ports. If you do want the service’s ports \nto be created and mapped to the host, specify the `--service-ports`\n\n```\ndocker compose run --service-ports web python manage.py shell\n```\n\nAlternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:\n\n```\ndocker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell\n```\n\n\nIf you start a service configured with links, the run command first checks to see if the linked service is running \nand starts the service if it is stopped. Once all the linked services are running, the run executes the command you \npassed it. For example, you could run:\n\n```\ndocker compose run db psql -h db -U docker\n```\n\nThis opens an interactive PostgreSQL shell for the linked `db` container.\n\nIf you do not want the run command to start linked containers, use the `--no-deps` flag:\n\n```\ndocker compose run --no-deps web python manage.py shell\n```\n\nIf you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:\n\n```\ndocker compose run --rm web python manage.py db upgrade\n```\n\nThis runs a database upgrade script, and removes the container when finished running, even if a restart policy is \nspecified in the service configuration."
-    the `web` service and runs `bash` as its command.\n`docker compose run web bash`\n\nCommands
+usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
-    you use with run start in new containers with configuration defined by that of
-    the service,\nincluding volumes, links, and other details. However, there are
-    two important differences:\n\nFirst, the command passed by `run` overrides the
-    command defined in the service configuration. For example, if the \n`web` service
-    configuration is started with `bash`, then `docker compose run web python app.py`
-    overrides it with \n`python app.py`.\n\nThe second difference is that the `docker
-    compose run` command does not create any of the ports specified in the \nservice
-    configuration. This prevents port collisions with already-open ports. If you do
-    want the service’s ports \nto be created and mapped to the host, specify the `--service-ports`\n\n```\ndocker
-    compose run --service-ports web python manage.py shell\n```\n\nAlternatively,
-    manual port mapping can be specified with the `--publish` or `-p` options, just
-    as when using docker run:\n\n```\ndocker compose run --publish 8080:80 -p 2022:22
-    -p 127.0.0.1:2021:21 web python manage.py shell\n```\n\n\nIf you start a service
-    configured with links, the run command first checks to see if the linked service
-    is running \nand starts the service if it is stopped. Once all the linked services
-    are running, the run executes the command you \npassed it. For example, you could
-    run:\n\n```\ndocker compose run db psql -h db -U docker\n```\n\nThis opens an
-    interactive PostgreSQL shell for the linked `db` container.\n\nIf you do not want
-    the run command to start linked containers, use the `--no-deps` flag:\n\n```\ndocker
-    compose run --no-deps web python manage.py shell\n```\n\nIf you want to remove
-    the container after running while overriding the container’s restart policy, use
-    the `--rm` flag:\n\n```\ndocker compose run --rm web python manage.py db upgrade\n```\n\nThis
-    runs a database upgrade script, and removes the container when finished running,
-    even if a restart policy is \nspecified in the service configuration."
-usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l
-    KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
 pname: docker compose
 plink: docker_compose.yaml
 options:
@@ -145,7 +119,7 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-  - option: volumes
+    - option: volume
       shorthand: v
       value_type: stringArray
       default_value: '[]'

docs/reference/docker_compose_stop.yaml

@@ -1,7 +1,6 @@
 command: docker compose stop
 short: Stop services
-long: Stops running containers without removing them. They can be started again with
+long: Stops running containers without removing them. They can be started again with `docker compose start`.
-    `docker compose start`.
 usage: docker compose stop [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_top.yaml

@@ -1,12 +1,10 @@
 command: docker compose top
 short: Display the running processes
 long: Displays the running processes.
-usage: docker compose top
+usage: docker compose top [SERVICES...]
 pname: docker compose
 plink: docker_compose.yaml
-examples: "```\n$ docker compose top\nexample_foo_1\nUID    PID      PPID     C    STIME
+examples: "```\n$ docker compose top\nexample_foo_1\nUID    PID      PPID     C    STIME   TTY   TIME       CMD\nroot   142353   142331   2    15:33   ?     00:00:00   ping localhost -c 5 \n```"
-    \  TTY   TIME       CMD\nroot   142353   142331   2    15:33   ?     00:00:00
-    \  ping localhost -c 5 \n```"
 deprecated: false
 experimental: false
 experimentalcli: false

docs/reference/docker_compose_up.yaml

@@ -1,19 +1,6 @@
 command: docker compose up
 short: Create and start containers
-long: "Builds, (re)creates, starts, and attaches to containers for a service.\n\nUnless
+long: "Builds, (re)creates, starts, and attaches to containers for a service.\n\nUnless they are already running, this command also starts any linked services.\n\nThe `docker compose up` command aggregates the output of each container (liked `docker compose logs --follow` does). \nWhen the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the \nbackground and leaves them running.\n\nIf there are existing containers for a service, and the service’s configuration or image was changed after the \ncontainer’s creation, `docker compose up` picks up the changes by stopping and recreating the containers \n(preserving mounted volumes). To prevent Compose from picking up changes, use the `--no-recreate` flag.\n\nIf you want to force Compose to stop and recreate all containers, use the `--force-recreate` flag.\n\nIf the process encounters an error, the exit code for this command is `1`.\nIf the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`."
-    they are already running, this command also starts any linked services.\n\nThe
-    `docker compose up` command aggregates the output of each container (liked `docker
-    compose logs --follow` does). \nWhen the command exits, all containers are stopped.
-    Running `docker compose up --detach` starts the containers in the \nbackground
-    and leaves them running.\n\nIf there are existing containers for a service, and
-    the service’s configuration or image was changed after the \ncontainer’s creation,
-    `docker compose up` picks up the changes by stopping and recreating the containers
-    \n(preserving mounted volumes). To prevent Compose from picking up changes, use
-    the `--no-recreate` flag.\n\nIf you want to force Compose to stop and recreate
-    all containers, use the `--force-recreate` flag.\n\nIf the process encounters
-    an error, the exit code for this command is `1`.\nIf the process is interrupted
-    using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit
-    code is `0`."
 usage: docker compose up [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
@@ -38,6 +25,15 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: attach
+      value_type: stringArray
+      default_value: '[]'
+      description: Attach to service output.
+      deprecated: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: attach-dependencies
       value_type: bool
       default_value: "false"