Re-order extends docs.

Signed-off-by: Daniel Nephin <[email protected]>

docs/extends.md

@@ -14,9 +14,159 @@ weight=2
 
 Compose supports two methods of sharing common configuration:
 
-1. Extending individual services with [the `extends` field](#extending-services)
-2. Extending entire Compose file by
+1. Extending an entire Compose file by
    [using multiple Compose files](#multiple-compose-files)
+2. Extending individual services with [the `extends` field](#extending-services)
+
+
+## Multiple Compose files
+
+Using multiple Compose files enables you to customize a Compose application
+for different environments or different workflows.
+
+### Understanding multiple Compose files
+
+By default, Compose reads two files, a `docker-compose.yml` and an optional
+`docker-compose.override.yml` file. By convention, the `docker-compose.yml`
+contains your base configuration. The override file, as its name implies, can
+contain configuration overrides for existing services or entirely new
+services.
+
+If a service is defined in both files, Compose merges the configurations using
+the same rules as the `extends` field (see [Adding and overriding
+configuration](#adding-and-overriding-configuration)), with one exception.  If a
+service contains `links` or `volumes_from` those fields are copied over and
+replace any values in the original service, in the same way single-valued fields
+are copied.
+
+To use multiple override files, or an override file with a different name, you
+can use the `-f` option to specify the list of files. Compose merges files in
+the order they're specified on the command line. See the [`docker-compose`
+command reference](./reference/docker-compose.md) for more information about
+using `-f`.
+
+When you use multiple configuration files, you must make sure all paths in the
+files are relative to the base Compose file (the first Compose file specified
+with `-f`). This is required because override files need not be valid
+Compose files. Override files can contain small fragments of configuration.
+Tracking which fragment of a service is relative to which path is difficult and
+confusing, so to keep paths easier to understand, all paths must be defined
+relative to the base file.
+
+### Example use case
+
+In this section are two common use cases for multiple compose files: changing a
+Compose app for different environments, and running administrative tasks
+against a Compose app.
+
+#### Different environments
+
+A common use case for multiple files is changing a development Compose app
+for a production-like environment (which may be production, staging or CI).
+To support these differences, you can split your Compose configuration into
+a few different files:
+
+Start with a base file that defines the canonical configuration for the
+services.
+
+**docker-compose.yml**
+
+    web:
+      image: example/my_web_app:latest
+      links:
+        - db
+        - cache
+
+    db:
+      image: postgres:latest
+
+    cache:
+      image: redis:latest
+
+In this example the development configuration exposes some ports to the
+host, mounts our code as a volume, and builds the web image.
+
+**docker-compose.override.yml**
+
+
+    web:
+      build: .
+      volumes:
+        - '.:/code'
+      ports:
+        - 8883:80
+      environment:
+        DEBUG: 'true'
+
+    db:
+      command: '-d'
+      ports:
+        - 5432:5432
+
+    cache:
+      ports:
+        - 6379:6379
+
+When you run `docker-compose up` it reads the overrides automatically.
+
+Now, it would be nice to use this Compose app in a production environment. So,
+create another override file (which might be stored in a different git
+repo or managed by a different team).
+
+**docker-compose.prod.yml**
+
+    web:
+      ports:
+        - 80:80
+      environment:
+        PRODUCTION: 'true'
+
+    cache:
+      environment:
+        TTL: '500'
+
+To deploy with this production Compose file you can run
+
+    docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+This deploys all three services using the configuration in
+`docker-compose.yml` and `docker-compose.prod.yml` (but not the
+dev configuration in `docker-compose.override.yml`).
+
+
+See [production](production.md) for more information about Compose in
+production.
+
+#### Administrative tasks
+
+Another common use case is running adhoc or administrative tasks against one
+or more services in a Compose app. This example demonstrates running a
+database backup.
+
+Start with a **docker-compose.yml**.
+
+    web:
+      image: example/my_web_app:latest
+      links:
+        - db
+
+    db:
+      image: postgres:latest
+
+In a **docker-compose.admin.yml** add a new service to run the database
+export or backup.
+
+    dbadmin:
+      build: database_admin/
+      links:
+        - db
+
+To start a normal environment run `docker-compose up -d`. To run a database
+backup, include the `docker-compose.admin.yml` as well.
+
+    docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
+        run dbadmin db-backup
+
 
 ## Extending services
 
@@ -123,7 +273,7 @@ common configuration:
       links:
         - queue
 
-### Adding and overriding configuration
+## Adding and overriding configuration
 
 Compose copies configurations from the original service over to the local one,
 **except** for `links` and `volumes_from`. These exceptions exist to avoid
@@ -211,153 +361,6 @@ In the case of `environment`, `labels`, `volumes` and `devices`, Compose
       - BAZ=local
 
 
-## Multiple Compose files
-
-Using multiple Compose files enables you to customize a Compose application
-for different environments or different workflows.
-
-### Understanding multiple Compose files
-
-By default, Compose reads two files, a `docker-compose.yml` and an optional
-`docker-compose.override.yml` file. By convention, the `docker-compose.yml`
-contains your base configuration. The override file, as its name implies, can
-contain configuration overrides for existing services or entirely new
-services.
-
-If a service is defined in both files, Compose merges the configurations using
-the same rules as the `extends` field (see [Adding and overriding
-configuration](#adding-and-overriding-configuration)), with one exception.  If a
-service contains `links` or `volumes_from` those fields are copied over and
-replace any values in the original service, in the same way single-valued fields
-are copied.
-
-To use multiple override files, or an override file with a different name, you
-can use the `-f` option to specify the list of files. Compose merges files in
-the order they're specified on the command line. See the [`docker-compose`
-command reference](./reference/docker-compose.md) for more information about
-using `-f`.
-
-When you use multiple configuration files, you must make sure all paths in the
-files are relative to the base Compose file (the first Compose file specified
-with `-f`). This is required because override files need not be valid
-Compose files. Override files can contain small fragments of configuration.
-Tracking which fragment of a service is relative to which path is difficult and
-confusing, so to keep paths easier to understand, all paths must be defined
-relative to the base file.
-
-### Example use case
-
-In this section are two common use cases for multiple compose files: changing a
-Compose app for different environments, and running administrative tasks
-against a Compose app.
-
-#### Different environments
-
-A common use case for multiple files is changing a development Compose app
-for a production-like environment (which may be production, staging or CI).
-To support these differences, you can split your Compose configuration into
-a few different files:
-
-Start with a base file that defines the canonical configuration for the
-services.
-
-**docker-compose.yml**
-
-    web:
-      image: example/my_web_app:latest
-      links:
-        - db
-        - cache
-
-    db:
-      image: postgres:latest
-
-    cache:
-      image: redis:latest
-
-In this example the development configuration exposes some ports to the
-host, mounts our code as a volume, and builds the web image.
-
-**docker-compose.override.yml**
-
-
-    web:
-      build: .
-      volumes:
-        - '.:/code'
-      ports:
-        - 8883:80
-      environment:
-        DEBUG: 'true'
-
-    db:
-      command: '-d'
-      ports:
-        - 5432:5432
-
-    cache:
-      ports:
-        - 6379:6379
-
-When you run `docker-compose up` it reads the overrides automatically.
-
-Now, it would be nice to use this Compose app in a production environment. So,
-create another override file (which might be stored in a different git
-repo or managed by a different team).
-
-**docker-compose.prod.yml**
-
-    web:
-      ports:
-        - 80:80
-      environment:
-        PRODUCTION: 'true'
-
-    cache:
-      environment:
-        TTL: '500'
-
-To deploy with this production Compose file you can run
-
-    docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-
-This deploys all three services using the configuration in
-`docker-compose.yml` and `docker-compose.prod.yml` (but not the
-dev configuration in `docker-compose.override.yml`).
-
-
-See [production](production.md) for more information about Compose in
-production.
-
-#### Administrative tasks
-
-Another common use case is running adhoc or administrative tasks against one
-or more services in a Compose app. This example demonstrates running a
-database backup.
-
-Start with a **docker-compose.yml**.
-
-    web:
-      image: example/my_web_app:latest
-      links:
-        - db
-
-    db:
-      image: postgres:latest
-
-In a **docker-compose.admin.yml** add a new service to run the database
-export or backup.
-
-    dbadmin:
-      build: database_admin/
-      links:
-        - db
-
-To start a normal environment run `docker-compose up -d`. To run a database
-backup, include the `docker-compose.admin.yml` as well.
-
-    docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
-        run dbadmin db-backup
 
 
 ## Compose documentation