Update docs to define and document new compose.yml file format

Add volume configuration reference section.

Signed-off-by: Joffrey F <joffrey@docker.com>

docs/compose-file.md

@@ -24,6 +24,64 @@ As with `docker run`, options specified in the Dockerfile (e.g., `CMD`,
 `EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to
 specify them again in `docker-compose.yml`.
 
+## Versioning
+
+It is possible to use different versions of the `compose.yml` format.
+Below are the formats currently supported by compose.
+
+
+### Version 1
+
+Compose files that do not declare a version are considered "version 1". In
+those files, all the [services](#service-configuration-reference) are declared
+at the root of the document.
+
+Version 1 files do not support the declaration of
+named [volumes](#volume-configuration-reference)
+
+Example:
+
+    web:
+      build: .
+      ports:
+       - "5000:5000"
+      volumes:
+       - .:/code
+       - logvolume01:/var/log
+      links:
+       - redis
+    redis:
+      image: redis
+
+
+### Version 2
+
+Compose files using the version 2 syntax must indicate the version number at
+the root of the document. All [services](#service-configuration-reference)
+must be declared under the `services` key.
+Named [volumes](#volume-configuration-reference) must be declared under the
+`volumes` key.
+
+Example:
+
+    version: 2
+    services:
+      web:
+        build: .
+        ports:
+         - "5000:5000"
+        volumes:
+         - .:/code
+         - logvolume01:/var/log
+        links:
+         - redis
+      redis:
+        image: redis
+    volumes:
+      logvolume01:
+        driver: default
+
+
 ## Service configuration reference
 
 This section contains a list of all configuration options supported by a service
@@ -413,6 +471,34 @@ Each of these is a single value, analogous to its
     stdin_open: true
     tty: true
 
+
+## Volume configuration reference
+
+While it is possible to declare volumes on the fly as part of the service
+declaration, this section allows you to create named volumes that can be
+reused across multiple services (without relying on `volumes_from`), and are
+easily retrieved and inspected using the docker command line or API.
+See the [docker volume](http://docs.docker.com/reference/commandline/volume/)
+subcommand documentation for more information.
+
+### driver
+
+Specify which volume driver should be used for this volume. Defaults to
+`local`. An exception will be raised if the driver is not available.
+
+      driver: foobar
+
+### driver_opts
+
+Specify a list of options as key-value pairs to pass to the driver for this
+volume. Those options are driver dependent - consult the driver's
+documentation for more information. Optional.
+
+      driver_opts:
+        foo: "bar"
+        baz: 1
+
+
 ## Variable substitution
 
 Your configuration options can contain environment variables. Compose uses the

docs/index.md

@@ -31,16 +31,22 @@ they can be run together in an isolated environment.
 
 A `docker-compose.yml` looks like this:
 
+    version: 2
+    services:
       web:
         build: .
         ports:
          - "5000:5000"
         volumes:
          - .:/code
+         - logvolume01:/var/log
         links:
          - redis
       redis:
         image: redis
+    volumes:
+      logvolume01:
+        driver: default
 
 For more information about the Compose file, see the
 [Compose file reference](compose-file.md)