expanded on pull command, added links to Compose samples (#3197)

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

_data/toc.yaml

@@ -1514,6 +1514,8 @@ manuals:
     title: Link Environment Variables (deprecated)
   - path: /compose/startup-order/
     title: Control startup order
+  - path: /compose/samples-for-compose/
+    title: Samples for Compose
 - sectiontitle: Docker Datacenter
   section:
   - path: /datacenter/install/aws/

compose/reference/pull.md

@@ -13,4 +13,45 @@ Options:
     --parallel              Pull multiple images in parallel.
 ```
 
-Pulls service images.
+Pulls an image associated with a service defined in a `docker-compose.yml` or `docker-stack.yml` file, but does not start containers based on those images.
+
+For example, suppose you have this `docker-compose.yml` file from the [Quickstart: Compose and Rails](/compose/rails.md) sample.
+
+```
+version: '2'
+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 `docker-compose.yml` file that defines the service, Docker will pull the postgres 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
+Pulling db (postgres:latest)...
+latest: Pulling from library/postgres
+cd0a524342ef: Pull complete
+9c784d04dcb0: Pull complete
+d99dddf7e662: Pull complete
+e5bff71e3ce6: Pull complete
+cb3e0a865488: Pull complete
+31295d654cd5: Pull complete
+fc930a4e09f5: Pull complete
+8650cce8ef01: Pull complete
+61949acd8e52: Pull complete
+527a203588c0: Pull complete
+26dec14ac775: Pull complete
+0efc0ed5a9e5: Pull complete
+40cd26695b38: Pull complete
+Digest: sha256:fd6c0e2a9d053bebb294bb13765b3e01be7817bf77b01d58c2377ff27a4a46dc
+Status: Downloaded newer image for postgres:latest
+```

compose/samples-for-compose.md

@@ -0,0 +1,35 @@
+---
+description: Summary of samples related to Compose
+keywords: documentation, docs, docker, compose, samples
+title: Samples for Compose
+notoc: true
+---
+
+The following samples show the various aspects of how to work with Docker Compose. As a prerequisite, be sure to [install Docker Compose](/compose/install/) if you have not already done so.
+
+The samples should help you to:
+
+- define services based on Docker images in [Compose files](/compose/compose-file.md) `docker-compose.yml` and
+`docker-stack.yml` files
+- understand the relationship between `docker-compose.yml` and [Dockerfiles](/engine/reference/builder.md)
+- learn how to make calls to your application services from Compose files
+- learn how to deploy applications and services to a [swarm](/engine/swarm.md)
+
+These samples focus specifically on Docker Compose:
+
+- [Quickstart: Compose and Django](/compose/django.md) - This quickstart
+guide demonstrates how to use Docker Compose to set up and run a simple
+Django/PostgreSQL app.
+
+- [Quickstart: Compose and Rails](/compose/rails.md) - This quickstart
+guide will show you how to use Docker Compose to set up and run a Rails/PostgreSQL
+app.
+
+- [Quickstart: Compose and WordPress](/compose/wordpress.md)
+
+These samples include working with Docker Compose as part of broader learning goals:
+
+- [Get Started with Docker](/get-started/index.md) - This multi-part tutorial covers writing your first app, data storage, networking, and swarms,
+and ends with your app running on production servers in the cloud.
+
+- [Deploying an app to a Swarm](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md) - This tutorial from [Docker Labs](https://github.com/docker/labs/blob/master/README.md) shows you how to create and customize a sample voting app, deploy it to a [swarm](/engine/swarm.md), test it, reconfigure the app, and redeploy.