Merge pull request #2777 from dnephin/reorder_docs

Re-order docs in menu, fix menu title capitalization, cleanup command reference

docs/compose-file.md

@@ -1,6 +1,6 @@
 <!--[metadata]>
 +++
-title = "Compose file reference"
+title = "Compose File Reference"
 description = "Compose file reference"
 keywords = ["fig, composition, compose, docker"]
 aliases = ["/compose/yml"]
@@ -903,7 +903,8 @@ It's more complicated if you're using particular configuration features:
             syslog-address: "tcp://192.168.0.42:123"
 
 -   `links` with environment variables: As documented in the
-    [environment variables reference](env.md), environment variables created by
+    [environment variables reference](link-env-deprecated.md), environment variables
+    created by
     links have been deprecated for some time. In the new Docker network system,
     they have been removed. You should either connect directly to the
     appropriate hostname or set the relevant environment variable yourself,

docs/extends.md

@@ -1,11 +1,11 @@
 <!--[metadata]>
 +++
-title = "Extending services in Compose"
+title = "Extending Services in Compose"
 description = "How to use Docker Compose's extends keyword to share configuration between files and projects"
 keywords = ["fig, composition, compose, docker, orchestration, documentation, docs"]
 [menu.main]
 parent="workw_compose"
-weight=2
+weight=20
 +++
 <![end-metadata]-->
 
@@ -42,7 +42,7 @@ 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
+command reference](./reference/overview.md) for more information about
 using `-f`.
 
 When you use multiple configuration files, you must make sure all paths in the

docs/faq.md

@@ -50,8 +50,8 @@ handling `SIGTERM` properly.
 Compose uses the project name to create unique identifiers for all of a
 project's  containers and other resources. To run multiple copies of a project,
 set a custom project name using the [`-p` command line
-option](./reference/docker-compose.md) or the [`COMPOSE_PROJECT_NAME`
-environment variable](./reference/overview.md#compose-project-name).
+option](./reference/overview.md) or the [`COMPOSE_PROJECT_NAME`
+environment variable](./reference/envvars.md#compose-project-name).
 
 ## What's the difference between `up`, `run`, and `start`?
 

docs/index.md

@@ -1,6 +1,6 @@
 <!--[metadata]>
 +++
-title = "Compose"
+title = "Docker Compose"
 description = "Introduction and Overview of Compose"
 keywords = ["documentation, docs,  docker, compose, orchestration,  containers"]
 [menu.main]

docs/env.md → docs/link-env-deprecated.md

@@ -1,15 +1,16 @@
 <!--[metadata]>
 +++
-title = "Environment variables reference"
+title = "Link Environment Variables"
 description = "Compose CLI reference"
 keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+aliases = ["/compose/env"]
 [menu.main]
 parent="workw_compose"
 weight=89
 +++
 <![end-metadata]-->
 
-# Compose environment variables reference
+# Link environment variables reference
 
 > **Note:** Environment variables are no longer the recommended method for connecting to linked services. Instead, you should use the link name (by default, the name of the linked service) as the hostname to connect to. See the [docker-compose.yml documentation](compose-file.md#links) for details.
 >

docs/networking.md

@@ -5,6 +5,7 @@ description = "How Compose sets up networking between containers"
 keywords = ["documentation, docs,  docker, compose, orchestration, containers, networking"]
 [menu.main]
 parent="workw_compose"
+weight=21
 +++
 <![end-metadata]-->
 
@@ -19,7 +20,11 @@ container for a service joins the default network and is both *reachable* by
 other containers on that network, and *discoverable* by them at a hostname
 identical to the container name.
 
-> **Note:** Your app's network is given a name based on the "project name", which is based on the name of the directory it lives in. You can override the project name with either the [`--project-name` flag](reference/docker-compose.md) or the [`COMPOSE_PROJECT_NAME` environment variable](reference/overview.md#compose-project-name).
+> **Note:** Your app's network is given a name based on the "project name",
+> which is based on the name of the directory it lives in. You can override the
+> project name with either the [`--project-name`
+> flag](reference/overview.md) or the [`COMPOSE_PROJECT_NAME` environment
+> variable](reference/envvars.md#compose-project-name).
 
 For example, suppose your app is in a directory called `myapp`, and your `docker-compose.yml` looks like this:
 

docs/overview.md

@@ -92,8 +92,8 @@ this project name to:
 
 The default project name is the basename of the project directory. You can set
 a custom project name by using the
-[`-p` command line option](./reference/docker-compose.md) or the
-[`COMPOSE_PROJECT_NAME` environment variable](./reference/overview.md#compose-project-name).
+[`-p` command line option](./reference/overview.md) or the
+[`COMPOSE_PROJECT_NAME` environment variable](./reference/envvars.md#compose-project-name).
 
 ### Preserve volume data when containers are created
 

docs/production.md

@@ -1,11 +1,11 @@
 <!--[metadata]>
 +++
-title = "Using Compose in production"
+title = "Using Compose in Production"
 description = "Guide to using Docker Compose in production"
 keywords = ["documentation, docs,  docker, compose, orchestration, containers,  production"]
 [menu.main]
 parent="workw_compose"
-weight=1
+weight=22
 +++
 <![end-metadata]-->
 

docs/reference/docker-compose.md

@@ -1,106 +0,0 @@
-<!--[metadata]>
-+++
-title = "docker-compose"
-description = "docker-compose Command Binary"
-keywords = ["fig, composition, compose, docker, orchestration, cli,  docker-compose"]
-[menu.main]
-parent = "smn_compose_cli"
-weight=-2
-+++
-<![end-metadata]-->
-
-
-# docker-compose Command
-
-```
-Usage:
-  docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
-  docker-compose -h|--help
-
-Options:
-  -f, --file FILE           Specify an alternate compose file (default: docker-compose.yml)
-  -p, --project-name NAME   Specify an alternate project name (default: directory name)
-  --verbose                 Show more output
-  -v, --version             Print version and exit
-
-Commands:
-  build              Build or rebuild services
-  help               Get help on a command
-  kill               Kill containers
-  logs               View output from containers
-  pause              Pause services
-  port               Print the public port for a port binding
-  ps                 List containers
-  pull               Pulls service images
-  restart            Restart services
-  rm                 Remove stopped containers
-  run                Run a one-off command
-  scale              Set number of containers for a service
-  start              Start services
-  stop               Stop services
-  unpause            Unpause services
-  up                 Create and start containers
-  version            Show the Docker-Compose version information
-```
-
-The Docker Compose binary. You use this command to build and manage multiple
-services in Docker containers.
-
-Use the `-f` flag to specify the location of a Compose configuration file. 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 successors.
-
-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.
-
-```
-webapp:
-  image: examples/web
-  ports:
-    - "8000:8000"
-  volumes:
-    - "/data"
-```
-
-If the `docker-compose.admin.yml` also specifies this same service, any matching
-fields will override the previous file. New values, add to the `webapp` service
-configuration.
-
-```
-webapp:
-  build: .
-  environment:
-    - DEBUG=1
-```
-
-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
-`docker-compose.yml` and a `docker-compose.override.yml` file. You must
-supply at least the `docker-compose.yml` file. If both files are present on the
-same directory level, Compose combines the two files into a single configuration.
-The configuration in the `docker-compose.override.yml` file is applied over and
-in addition to the values in the `docker-compose.yml` file.
-
-See also the `COMPOSE_FILE` [environment variable](overview.md#compose-file).
-
-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. See also the `COMPOSE_PROJECT_NAME` [environment variable](
-overview.md#compose-project-name)
-
-
-## Where to go next
-
-* [CLI environment variables](overview.md)
-* [Command line reference](index.md)

docs/reference/envvars.md

@@ -0,0 +1,78 @@
+<!--[metadata]>
++++
+title = "CLI Environment Variables"
+description = "CLI Environment Variables"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+parent = "smn_compose_cli"
+weight=-1
++++
+<![end-metadata]-->
+
+
+# CLI Environment Variables
+
+Several environment variables are available for you to configure the Docker Compose command-line behaviour.
+
+Variables starting with `DOCKER_` are the same as those used to configure the
+Docker command-line client. If you're using `docker-machine`, then the `eval "$(docker-machine env my-docker-vm)"` command should set them to their correct values. (In this example, `my-docker-vm` is the name of a machine you created.)
+
+## COMPOSE\_PROJECT\_NAME
+
+Sets the project name. This value is prepended along with the service name to the container container on start up. For example, if you project name is `myapp` and it includes two services `db` and `web` then compose starts containers named  `myapp_db_1` and `myapp_web_1` respectively.
+
+Setting this is optional. If you do not set this, the `COMPOSE_PROJECT_NAME`
+defaults to the `basename` of the project directory. See also the `-p`
+[command-line option](overview.md).
+
+## COMPOSE\_FILE
+
+Specify the file containing the compose configuration. If not provided,
+Compose looks for a file named  `docker-compose.yml` in the current directory
+and then each parent directory in succession until a file by that name is
+found. See also the `-f` [command-line option](overview.md).
+
+## COMPOSE\_API\_VERSION
+
+The Docker API only supports requests from clients which report a specific
+version. If you receive a `client and server don't have same version error` using
+`docker-compose`, you can workaround this error by setting this environment
+variable. Set the version value to match the server version.
+
+Setting this variable is intended as a workaround for situations where you need
+to run temporarily with a mismatch between the client and server version. For
+example, if you can upgrade the client but need to wait to upgrade the server.
+
+Running with this variable set and a known mismatch does prevent some Docker
+features from working properly. The exact features that fail would depend on the
+Docker client and server versions. For this reason, running with this variable
+set is only intended as a workaround and it is not officially supported.
+
+If you run into problems running with this set, resolve the mismatch through
+upgrade and remove this setting to see if your problems resolve before notifying
+support.
+
+## DOCKER\_HOST
+
+Sets the URL of the `docker` daemon. As with the Docker client, defaults to `unix:///var/run/docker.sock`.
+
+## DOCKER\_TLS\_VERIFY
+
+When set to anything other than an empty string, enables TLS communication with
+the `docker` daemon.
+
+## DOCKER\_CERT\_PATH
+
+Configures the path to the `ca.pem`, `cert.pem`, and `key.pem` files used for TLS verification. Defaults to `~/.docker`.
+
+## COMPOSE\_HTTP\_TIMEOUT
+
+Configures the time (in seconds) a request to the Docker daemon is allowed to hang before Compose considers
+it failed. Defaults to 60 seconds.
+
+
+## Related Information
+
+- [User guide](../index.md)
+- [Installing Compose](../install.md)
+- [Compose file reference](../compose-file.md)

docs/reference/index.md

@@ -1,6 +1,6 @@
 <!--[metadata]>
 +++
-title = "Command line reference"
+title = "Command-line Reference"
 description = "Compose CLI reference"
 keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
 [menu.main]
@@ -12,8 +12,9 @@ weight=80
 
 ## Compose command-line reference
 
-The following pages describe the usage information for the [docker-compose](docker-compose.md) subcommands. You can also see this information by running `docker-compose [SUBCOMMAND] --help` from the command line.
+The following pages describe the usage information for the [docker-compose](overview.md) subcommands. You can also see this information by running `docker-compose [SUBCOMMAND] --help` from the command line.
 
+* [docker-compose](overview.md)
 * [build](build.md)
 * [config](config.md)
 * [create](create.md)
@@ -37,5 +38,5 @@ The following pages describe the usage information for the [docker-compose](dock
 
 ## Where to go next
 
-* [CLI environment variables](overview.md)
-* [docker-compose Command](docker-compose.md)
+* [CLI environment variables](envvars.md)
+* [docker-compose Command](overview.md)

docs/reference/overview.md

@@ -1,8 +1,9 @@
 <!--[metadata]>
 +++
-title = "Introduction to the CLI"
-description = "Introduction to the CLI"
-keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+title = "Overview of docker-compose CLI"
+description = "Overview of docker-compose CLI"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  docker-compose"]
+aliases = ["/compose/reference/docker-compose/"]
 [menu.main]
 parent = "smn_compose_cli"
 weight=-2
@@ -10,80 +11,107 @@ weight=-2
 <![end-metadata]-->
 
 
-# Introduction to the CLI
-
-This section describes the subcommands you can use with the `docker-compose` command.  You can run subcommand against one or more services. To run against a specific service, you supply the service name from your compose configuration. If you do not specify the service name, the command runs against all the services in your configuration.
-
-
-## Commands
-
-* [docker-compose Command](docker-compose.md)
-* [CLI Reference](index.md)
-
-
-## Environment Variables
-
-Several environment variables are available for you to configure the Docker Compose command-line behaviour.
-
-Variables starting with `DOCKER_` are the same as those used to configure the
-Docker command-line client. If you're using `docker-machine`, then the `eval "$(docker-machine env my-docker-vm)"` command should set them to their correct values. (In this example, `my-docker-vm` is the name of a machine you created.)
-
-### COMPOSE\_PROJECT\_NAME
-
-Sets the project name. This value is prepended along with the service name to the container container on start up. For example, if you project name is `myapp` and it includes two services `db` and `web` then compose starts containers named  `myapp_db_1` and `myapp_web_1` respectively.
-
-Setting this is optional. If you do not set this, the `COMPOSE_PROJECT_NAME`
-defaults to the `basename` of the project directory. See also the `-p`
-[command-line option](docker-compose.md).
-
-### COMPOSE\_FILE
-
-Specify the file containing the compose configuration. If not provided,
-Compose looks for a file named  `docker-compose.yml` in the current directory
-and then each parent directory in succession until a file by that name is
-found. See also the `-f` [command-line option](docker-compose.md).
-
-### COMPOSE\_API\_VERSION
-
-The Docker API only supports requests from clients which report a specific
-version. If you receive a `client and server don't have same version error` using
-`docker-compose`, you can workaround this error by setting this environment
-variable. Set the version value to match the server version.
-
-Setting this variable is intended as a workaround for situations where you need
-to run temporarily with a mismatch between the client and server version. For
-example, if you can upgrade the client but need to wait to upgrade the server.
-
-Running with this variable set and a known mismatch does prevent some Docker
-features from working properly. The exact features that fail would depend on the
-Docker client and server versions. For this reason, running with this variable
-set is only intended as a workaround and it is not officially supported.
-
-If you run into problems running with this set, resolve the mismatch through
-upgrade and remove this setting to see if your problems resolve before notifying
-support.
-
-### DOCKER\_HOST
-
-Sets the URL of the `docker` daemon. As with the Docker client, defaults to `unix:///var/run/docker.sock`.
-
-### DOCKER\_TLS\_VERIFY
-
-When set to anything other than an empty string, enables TLS communication with
-the `docker` daemon.
-
-### DOCKER\_CERT\_PATH
-
-Configures the path to the `ca.pem`, `cert.pem`, and `key.pem` files used for TLS verification. Defaults to `~/.docker`.
-
-### COMPOSE\_HTTP\_TIMEOUT
-
-Configures the time (in seconds) a request to the Docker daemon is allowed to hang before Compose considers
-it failed. Defaults to 60 seconds.
-
-
-## Related Information
-
-- [User guide](../index.md)
-- [Installing Compose](../install.md)
-- [Compose file reference](../compose-file.md)
+# Overview of docker-compose CLI
+
+This page provides the usage information for the `docker-compose` Command.
+You can also see this information by running `docker-compose --help` from the
+command line.
+
+```
+Define and run multi-container applications with Docker.
+
+Usage:
+  docker-compose [-f=<arg>...] [options] [COMMAND] [ARGS...]
+  docker-compose -h|--help
+
+Options:
+  -f, --file FILE           Specify an alternate compose file (default: docker-compose.yml)
+  -p, --project-name NAME   Specify an alternate project name (default: directory name)
+  --verbose                 Show more output
+  -v, --version             Print version and exit
+
+Commands:
+  build              Build or rebuild services
+  config             Validate and view the compose file
+  create             Create services
+  down               Stop and remove containers, networks, images, and volumes
+  events             Receive real time events from containers
+  help               Get help on a command
+  kill               Kill containers
+  logs               View output from containers
+  pause              Pause services
+  port               Print the public port for a port binding
+  ps                 List containers
+  pull               Pulls service images
+  restart            Restart services
+  rm                 Remove stopped containers
+  run                Run a one-off command
+  scale              Set number of containers for a service
+  start              Start services
+  stop               Stop services
+  unpause            Unpause services
+  up                 Create and start containers
+  version            Show the Docker-Compose version information
+
+```
+
+The Docker Compose binary. You use this command to build and manage multiple
+services in Docker containers.
+
+Use the `-f` flag to specify the location of a Compose configuration file. 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 successors.
+
+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.
+
+```
+webapp:
+  image: examples/web
+  ports:
+    - "8000:8000"
+  volumes:
+    - "/data"
+```
+
+If the `docker-compose.admin.yml` also specifies this same service, any matching
+fields will override the previous file. New values, add to the `webapp` service
+configuration.
+
+```
+webapp:
+  build: .
+  environment:
+    - DEBUG=1
+```
+
+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
+`docker-compose.yml` and a `docker-compose.override.yml` file. You must
+supply at least the `docker-compose.yml` file. If both files are present on the
+same directory level, Compose combines the two files into a single configuration.
+The configuration in the `docker-compose.override.yml` file is applied over and
+in addition to the values in the `docker-compose.yml` file.
+
+See also the `COMPOSE_FILE` [environment variable](envvars.md#compose-file).
+
+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. See also the `COMPOSE_PROJECT_NAME` [environment variable](
+envvars.md#compose-project-name)
+
+
+## Where to go next
+
+* [CLI environment variables](envvars.md)