Merge pull request #1416 from docker/docs

reference documentation

docs/reference/compose.md

@@ -0,0 +1,99 @@
+
+
+## Description
+
+You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
+multiple services in Docker containers.
+
+### Use `-f` to specify 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:
+
+```
+$ 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: 
+```
+docker compose -f ~/sandbox/rails/compose.yaml pull db
+```
+
+### Use `-p` to specify a project name
+
+Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t 
+specify the flag, Compose uses the current directory name. 
+Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
+
+Most compose subcommand can be ran without a compose file, just passing 
+project name to retrieve the relevant resources.
+
+```
+$ 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` will start 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` will be enabled.
+
+Profiles can also be set by `COMPOSE_PROFILES` 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 for to the `-p` flag,
+and so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag.
+
+If flags are explicitly set on command line, associated environment variable is ignored

docs/reference/compose_convert.md

@@ -0,0 +1,9 @@
+
+
+## Description
+
+`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,
+it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into 
+fully defined Compose model. 
+
+To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`

docs/reference/compose_down.md

@@ -0,0 +1,17 @@
+
+
+## Description
+
+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 will not be automatically
+mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
+named volumes.

docs/reference/compose_events.md

@@ -0,0 +1,22 @@
+
+## Description
+
+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](/engine/reference/commandline/events/#object-types).

docs/reference/compose_exec.md

@@ -0,0 +1,7 @@
+
+## Description
+
+This is the equivalent of `docker exec` targeting a Compose service. 
+
+With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so 
+you can use a command such as `docker compose exec web sh` to get an interactive prompt.

docs/reference/compose_kill.md

@@ -0,0 +1,8 @@
+
+## Description
+
+Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example:
+
+```
+docker-compose kill -s SIGINT
+```

docs/reference/compose_logs.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Displays log output from services.

docs/reference/compose_ls.md

@@ -0,0 +1,4 @@
+
+## Description
+
+List Compose projects running on platform.

docs/reference/compose_pause.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Pauses running containers of a service. They can be unpaused with `docker compose unpause`.

docs/reference/compose_ps.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Lists containers for a Compose project.

docs/reference/compose_pull.md

@@ -0,0 +1,49 @@
+
+## Description
+
+Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on 
+those images.
+
+
+## Examples 
+
+suppose you have this `compose.yaml` file from the Quickstart: [Compose and Rails sample](compose/rails/).
+
+```yaml
+services:
+  db:
+    image: postgres
+  web:
+    build: .
+    command: bundle exec rails s -p 3000 -b '0.0.0.0'
+    volumes:
+    - .:/myapp
+    ports:
+    - "3000:3000"
+    depends_on:
+    - db
+```
+
+If you run `docker compose pull ServiceName` in the same directory as the `ccompose.yaml` file that defines the service, 
+Docker pulls the associated image. For example, to call the postgres image configured as the db service in our example, 
+you would run `docker compose pull db`.
+
+```
+$ docker compose pull db
+[+] Running 1/15
+ ⠸ db Pulling                                                             12.4s
+   ⠿ 45b42c59be33 Already exists                                           0.0s
+   ⠹ 40adec129f1a Downloading  3.374MB/4.178MB                             9.3s
+   ⠹ b4c431d00c78 Download complete                                        9.3s
+   ⠹ 2696974e2815 Download complete                                        9.3s
+   ⠹ 564b77596399 Downloading  5.622MB/7.965MB                             9.3s
+   ⠹ 5044045cf6f2 Downloading  216.7kB/391.1kB                             9.3s
+   ⠹ d736e67e6ac3 Waiting                                                  9.3s
+   ⠹ 390c1c9a5ae4 Waiting                                                  9.3s
+   ⠹ c0e62f172284 Waiting                                                  9.3s
+   ⠹ ebcdc659c5bf Waiting                                                  9.3s
+   ⠹ 29be22cb3acc Waiting                                                  9.3s
+   ⠹ f63c47038e66 Waiting                                                  9.3s
+   ⠹ 77a0c198cde5 Waiting                                                  9.3s
+   ⠹ c8752d5b785c Waiting                                                  9.3s
+``̀

docs/reference/compose_push.md

@@ -0,0 +1,21 @@
+
+## Description
+
+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
+```

docs/reference/compose_rm.md

@@ -0,0 +1,18 @@
+
+## Description
+
+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`.
+
+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`:
+
+```
+$ docker compose rm
+Going to remove djangoquickstart_web_run_1
+Are you sure? [yN] y
+Removing djangoquickstart_web_run_1 ... done
+```

docs/reference/compose_run.md

@@ -0,0 +1,53 @@
+
+
+Runs a one-time command against a service. 
+
+the following command starts the `web` service and runs `bash` as its command.
+`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`
+
+```
+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:
+
+```
+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:
+
+```
+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:
+
+```
+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:
+
+```
+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.

docs/reference/compose_start.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Starts existing containers for a service.

docs/reference/compose_stop.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Stops running containers without removing them. They can be started again with `docker compose start`.

docs/reference/compose_top.md

@@ -0,0 +1,13 @@
+
+## Description
+
+Displays the running processes.
+
+## Examples
+
+```
+$ docker compose top
+sample_foo_1
+UID    PID      PPID     C    STIME   TTY   TIME       CMD
+root   142353   142331   2    15:33   ?     00:00:00   ping localhost -c 5 
+```

docs/reference/compose_unpause.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Unpauses paused containers of a service.

docs/reference/compose_up.md

@@ -0,0 +1,19 @@
+
+## Description
+
+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 (liked `docker compose logs --follow` does). 
+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`.

docs/reference/docker_compose.yaml

@@ -1,6 +1,51 @@
 command: docker compose
 short: Docker Compose
-long: Docker Compose
+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\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"
 pname: docker
 plink: docker.yaml
 cname:

docs/reference/docker_compose_convert.yaml

@@ -1,7 +1,10 @@
 command: docker compose convert
 aliases: config
 short: Converts the compose file to platform's canonical format
-long: Converts the compose file to platform's canonical format
+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."
 usage: docker compose convert SERVICES
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_down.yaml

@@ -1,6 +1,19 @@
 command: docker compose down
 short: Stop and remove containers, networks
-long: Stop and remove containers, networks
+long: |-
+    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 will not be automatically
+    mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
+    named volumes.
 usage: docker compose down
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_events.yaml

@@ -1,6 +1,25 @@
 command: docker compose events
 short: Receive real time events from containers.
-long: Receive real time events from containers.
+long: |-
+    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](/engine/reference/commandline/events/#object-types).
 usage: docker compose events [options] [--] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_exec.yaml

@@ -1,6 +1,9 @@
 command: docker compose exec
 short: Execute a command in a running container.
-long: Execute a command in a running container.
+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."
 usage: docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_kill.yaml

@@ -1,6 +1,11 @@
 command: docker compose kill
 short: Force stop service containers.
-long: Force stop service containers.
+long: |-
+    Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example:
+
+    ```
+    docker-compose kill -s SIGINT
+    ```
 usage: docker compose kill [options] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_logs.yaml

@@ -1,6 +1,6 @@
 command: docker compose logs
 short: View output from containers
-long: View output from containers
+long: Displays log output from services.
 usage: docker compose logs [service...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_ls.yaml

@@ -1,6 +1,6 @@
 command: docker compose ls
 short: List running compose projects
-long: List running compose projects
+long: List Compose projects running on platform.
 usage: docker compose ls
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_pause.yaml

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

docs/reference/docker_compose_ps.yaml

@@ -1,6 +1,6 @@
 command: docker compose ps
 short: List containers
-long: List containers
+long: Lists containers for a Compose project.
 usage: docker compose ps
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_pull.yaml

@@ -1,6 +1,7 @@
 command: docker compose pull
 short: Pull service images
-long: Pull service images
+long: "Pulls an image associated with a service defined in a `compose.yaml` file,
+    but does not start containers based on \nthose images."
 usage: docker compose pull [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
@@ -24,6 +25,29 @@ options:
     experimentalcli: false
     kubernetes: false
     swarm: false
+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``̀"
 deprecated: false
 experimental: false
 experimentalcli: false

docs/reference/docker_compose_push.yaml

@@ -1,6 +1,11 @@
 command: docker compose push
 short: Push service images
-long: Push service images
+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```"
 usage: docker compose push [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_rm.yaml

@@ -1,6 +1,21 @@
 command: docker compose rm
 short: Removes stopped service containers
-long: Removes stopped service containers
+long: |-
+    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`.
+
+    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`:
+
+    ```
+    $ docker compose rm
+    Going to remove djangoquickstart_web_run_1
+    Are you sure? [yN] y
+    Removing djangoquickstart_web_run_1 ... done
+    ```
 usage: docker compose rm [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_start.yaml

@@ -1,6 +1,6 @@
 command: docker compose start
 short: Start services
-long: Start services
+long: Starts existing containers for a service.
 usage: docker compose start [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_stop.yaml

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

docs/reference/docker_compose_top.yaml

@@ -1,9 +1,12 @@
 command: docker compose top
 short: Display the running processes
-long: Display the running processes
+long: Displays the running processes.
 usage: docker compose top
 pname: docker compose
 plink: docker_compose.yaml
+examples: "```\n$ docker compose top\nsample_foo_1\nUID    PID      PPID     C    STIME
+    \  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_unpause.yaml

@@ -1,6 +1,6 @@
 command: docker compose unpause
 short: unpause services
-long: unpause services
+long: Unpauses paused containers of a service.
 usage: docker compose unpause [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_up.yaml

@@ -1,6 +1,19 @@
 command: docker compose up
 short: Create and start containers
-long: Create and start containers
+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`."
 usage: docker compose up [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
@@ -137,6 +150,15 @@ options:
     experimentalcli: false
     kubernetes: false
     swarm: false
+  - option: quiet-pull
+    value_type: bool
+    default_value: "false"
+    description: Pull without printing progress information.
+    deprecated: false
+    experimental: false
+    experimentalcli: false
+    kubernetes: false
+    swarm: false
   - option: remove-orphans
     value_type: bool
     default_value: "false"