Better examples to show Compose file structure, expand/collapse accordion (#3967)

* better examples to show Compose file structure Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * cleaned up leading spaces in Compose file example Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * cleaned up leading spaces, added a test file Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * expand/collapse accordion full implementation, explanation in test.md Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * delete temporary test file from PR Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * fix accordion to work on mobile (cursor style) Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * verified fix for mobile worked, added same to test.md, updated notes and content Signed-off-by: Victoria Bialas <victoria.bialas@docker.com> * Clarifed details on test page, fixed references for FontAwesome icons Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
2017-07-28 12:32:53 -07:00 · 2017-07-28 12:32:53 -07:00 · eb25815fb9
parent 52644895c0
commit eb25815fb9
4 changed files with 285 additions and 16 deletions
--- a/_scss/_utilities.scss
+++ b/_scss/_utilities.scss
@ -58,10 +58,37 @@ i.fa.fa-outdent {
    padding: 0px 15px 10px 15px;
 }

+
+/*
+*
+* Inline graphics and icons (like the whale menu icon in d4mac, d4win)
+*
+*/
+
 img.inline {
    display: inline;
 }

+
+/*
+*
+* Bootstrap expand/collapse accordions
+*
+*/
+
+.panel-heading .chevron:after {
+    content: "\f0d8";
+}
+
+.panel-heading.collapsed .chevron:after {
+    content: "\f0d7";
+}
+
+.panel-heading:hover{
+    background: #fafdfe;
+}
+
+
 /*
 * Search *********************************************************************
 *
--- a/compose/compose-file/index.md
+++ b/compose/compose-file/index.md
@ -31,10 +31,6 @@ a section in the configuration file such as `build`, `deploy`, `depends_on`,
 sub-topics. This maps to the `<key>: <option>: <value>` indent structure of the
 Compose file.

-The best way to grok the layout and syntax of a Compose file is to
-read [Get started with Docker Compose](/compose/gettingstarted/) and look
-at files included in [sample applications](https://docs.docker.com/samples/).
-
 A good place to start is the [Getting Started](/get-started/index.md) tutorial
 which uses version 3 Compose stack files to implement multi-container apps,
 service definitions, and swarm mode. Here are some Compose files used in the
@ -44,8 +40,110 @@ tutorial.

 - [Adding a new service and redeploying](/get-started/part5.md#adding-a-new-service-and-redeploying)

-Another example of a Compose file is included in the Docker Labs topic, [Deploying an app to a Swarm](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md).
+Another good example is the Compose file for the voting app sample used in the
+[Docker for Beginners lab](https://github.com/docker/labs/tree/master/beginner/)
+topic on [Deploying an app to a
+Swarm](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md).
+Click to show/hide the example Compose file below.

+<div class="panel panel-default">
+    <div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
+    Example Compose file version 3
+    <i class="chevron fa fa-fw"></i></div>
+    <div class="collapse block" id="collapseSample1">
+<pre><code>
+version: "3"
+services:
+
+redis:
+  image: redis:alpine
+  ports:
+    - "6379"
+  networks:
+    - frontend
+  deploy:
+    replicas: 2
+    update_config:
+      parallelism: 2
+      delay: 10s
+    restart_policy:
+      condition: on-failure
+db:
+  image: postgres:9.4
+  volumes:
+    - db-data:/var/lib/postgresql/data
+  networks:
+    - backend
+  deploy:
+    placement:
+      constraints: [node.role == manager]
+vote:
+  image: dockersamples/examplevotingapp_vote:before
+  ports:
+    - 5000:80
+  networks:
+    - frontend
+  depends_on:
+    - redis
+  deploy:
+    replicas: 2
+    update_config:
+      parallelism: 2
+    restart_policy:
+      condition: on-failure
+result:
+  image: dockersamples/examplevotingapp_result:before
+  ports:
+    - 5001:80
+  networks:
+    - backend
+  depends_on:
+    - db
+  deploy:
+    replicas: 1
+    update_config:
+      parallelism: 2
+      delay: 10s
+    restart_policy:
+      condition: on-failure
+
+worker:
+  image: dockersamples/examplevotingapp_worker
+  networks:
+    - frontend
+    - backend
+  deploy:
+    mode: replicated
+    replicas: 1
+    labels: [APP=VOTING]
+    restart_policy:
+      condition: on-failure
+      delay: 10s
+      max_attempts: 3
+      window: 120s
+    placement:
+      constraints: [node.role == manager]
+
+visualizer:
+  image: dockersamples/visualizer:stable
+  ports:
+    - "8080:8080"
+  stop_grace_period: 1m30s
+  volumes:
+    - "/var/run/docker.sock:/var/run/docker.sock"
+  deploy:
+    placement:
+      constraints: [node.role == manager]
+
+networks:
+  frontend:
+  backend:
+
+volumes:
+  db-data:
+</code></pre>
+    </div>
+</div>

 ## Service configuration reference

@ -79,16 +177,28 @@ definition in version 3.
 Configuration options that are applied at build time.

 `build` can be specified either as a string containing a path to the build
-context, or an object with the path specified under [context](#context) and
-optionally [dockerfile](#dockerfile) and [args](#args).
+context:

+```none
+version: '2'
+services:
+  webapp:
    build: ./dir
+```

+Or, as an an object with the path specified under [context](#context) and
+optionally [Dockerfile](#dockerfile) and [args](#args):
+
+```none
+version: '2'
+services:
+  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1
+```

 If you specify `image` as well as `build`, then Compose names the built image
 with the `webapp` and optional `tag` specified in `image`:
@ -783,7 +893,7 @@ list are processed from the top down. For the same variable specified in file
 listed below (after), then the value from `b.env` stands. For example, given the
 following declaration in `docker_compose.yml`:

-```yaml
+```none
 services:
  some-service:
    env_file:
@ -1093,7 +1203,10 @@ The general format is shown here.
            aliases:
             - alias2

-In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network.
+In the example below, three services are provided (`web`, `worker`, and `db`),
+along with two networks (`new` and `legacy`). The `db` service is reachable at
+the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on
+the `legacy` network.

    version: '2'

@ -1387,13 +1500,53 @@ more information.

 ### volumes

+Mount host paths or named volumes, specified as sub-options to a service.
+
+You can mount a host path as part of a definition for a single service, and
+there is no need to define it in the top level `volumes` key.
+
+But, if you want to reuse a volume across multiple services, then define a named
+volume in the [top-level `volumes` key](#volume-configuration-reference). Use
+named volumes with [services, swarms, and stack
+files](#volumes-for-services-swarms-and-stack-files).
+
 > **Note**: The top-level
-> [volumes](#volume-configuration-reference) option defines
+> [volumes](#volume-configuration-reference) key defines
 > a named volume and references it from each service's `volumes` list. This replaces `volumes_from` in earlier versions of the Compose file format. (See [Docker Volumes](/engine/userguide/dockervolumes.md) and
 [Volume Plugins](/engine/extend/plugins_volume.md) for general information on volumes.)

-Mount host paths or named volumes. Named volumes must be defined in the
-[top-level `volumes` key](#volume-configuration-reference). Use named volumes with [services, swarms, and stack files](#volumes-for-services-swarms-and-stack-files).
+This example shows a named volume (`db-data`) being used by the `postgres` service, and a mounted volume for a single service (under the `redis` service).
+
+```none
+version: "3"
+
+services:
+
+  web:
+    nginx:alpine
+    ports:
+    - "80:80"
+
+  postgres:
+    image: postgres:9.4
+    volumes:
+      - db-data:/var/lib/db
+
+  backup:
+    image: postgres:9.4
+    volumes:
+      - db-data:/var/lib/backup/data
+
+  redis:
+    image: redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - ./data:/data
+
+volumes:
+  db-data:
+```

 #### Short syntax

@ -1440,6 +1593,16 @@ expressed in the short form.


 ```none
+version: "3"
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+
+networks:
+  webnet:
+
 volumes:
  - type: volume
    source: mydata
@ -1475,7 +1638,7 @@ Labs](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md)
 configured as a named volume in order to persist the data on the swarm,
 _and_ is constrained to run only on `manager` nodes. Here is the relevant snip-it from that file:

-```
+```none
 version: "3"
 services:
  db:
@ -1511,7 +1674,7 @@ are visible on the host.

 Here is an example of configuring a volume as `cached`:

-```
+```none
 version: '3'
 services:
  php:
@ -1526,7 +1689,6 @@ Full detail on these flags, the problems they solve, and their
 `docker run` counterparts is in the Docker for Mac topic [Performance tuning for
 volume mounts (shared filesystems)](/docker-for-mac/osxfs-caching.md).

-
 ### restart

 `no` is the default restart policy, and it will not restart a container under
--- a/compose/overview.md
+++ b/compose/overview.md
@ -156,7 +156,7 @@ and destroy isolated testing environments for your test suite. By defining the f
 Compose has traditionally been focused on development and testing workflows,
 but with each release we're making progress on more production-oriented features. You can use Compose to deploy to a remote Docker Engine. The Docker Engine may be a single instance provisioned with
 [Docker Machine](/machine/overview.md) or an entire
-[Docker Swarm](/swarm/overview.md) cluster.
+[Docker Swarm](/engine/swarm/index.md) cluster.

 For details on using production-oriented features, see
 [compose in production](production.md) in this documentation.
--- a/test.md
+++ b/test.md
@ -335,6 +335,86 @@ then it will take up the whole row.</div>
 then it will take up the whole row.</div>
 </div>

+### Expand/Collapse accordions
+
+You can use the Bootstrap and CSS to add expand/collapse accordions. This
+implementation makes use of the `.panel-heading` classes in
+[`_utilities.scss`](/_scss/_utilities.scss), along with [FontAwesome
+icons](http://fontawesome.io/cheatsheet/){: target="_blank" class="_" }
+<i class="fa fa-caret-down" aria-hidden="true"></i> (fa-caret-down) and
+<i class="fa fa-caret-up" aria-hidden="true"></i> (fa-caret-up).
+
+Adding `block` to the `div` class `collapse` gives you some padding around the
+sample content. This works nicely for standard text. If you have a code sample,
+the padding renders as white space around the code block grey background. If we
+don't like this effect, we can remove `block` for code samples.
+
+The `style="cursor: pointer"` tag enables the expand/collapse functionality to
+work on mobile. (You can use the [Xcode iPhone simulator](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/GettingStartedwithiOSSimulator/GettingStartedwithiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH5-SW4){: target="_blank" class="_" } to test on mobile.)
+
+There are a lot of samples out there for Bootstrap accordions. This is the model
+we used: [PPxOJX accordion sample with HTML and
+CSS](https://codepen.io/anon/pen/PPxOJX){: target="_blank" class="_" }. (Here is
+another example, but it uses Javascript, whereas the implementation shown
+[here](https://www.bootply.com/89084){: target="_blank" class="_" } is Bootstrap
+and CSS only.)
+
+> Make sure `data-target`'s and `id`'s match, and are unique
+>
+>For each drop-down, the value for `data-target` and
+`collapse` `id` must match, and id's must be unique per page. In this example,
+we name these `collapseSample1` and `collapseSample2`. Check out the
+[Compose file structure example](/compose/compose-file/index.md#compose-file-structure-and-examples)
+to see another example.
+{: .important-vanilla}
+
+<div class="panel panel-default">
+    <div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
+    Docker hello-world example
+    <i class="chevron fa fa-fw"></i></div>
+    <div class="collapse block" id="collapseSample1">
+<pre><code>
+$ docker run hello-world
+Unable to find image 'hello-world:latest' locally
+latest: Pulling from library/hello-world
+b04784fba78d: Pull complete
+Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
+Status: Downloaded newer image for hello-world:latest
+
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+
+To generate this message, Docker took the following steps:
+ 1. The Docker client contacted the Docker daemon.
+ 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+ 3. The Docker daemon created a new container from that image which runs the
+    executable that produces the output you are currently reading.
+ 4. The Docker daemon streamed that output to the Docker client, which sent it
+    to your terminal.
+
+To try something more ambitious, you can run an Ubuntu container with:
+ $ docker run -it ubuntu bash
+
+Share images, automate workflows, and more with a free Docker ID:
+ https://cloud.docker.com/
+
+For more examples and ideas, visit:
+ https://docs.docker.com/engine/userguide/
+
+</code></pre>
+    </div>
+    <div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample2"  style="cursor: pointer"> Another Sample <i class="chevron fa fa-fw"></i></div>
+    <div class="collapse block" id="collapseSample2">
+<p>
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.</p>
+  </div>
+</div>
+
 ### Columnar text

 You can use the CSS `column-count` to flow your text into multiple columns.