Merge pull request #2509 from thaJeztah/19.03_backport_docs_fixes

[19.03 backport] documentation fixes

docs/reference/builder.md

@@ -743,8 +743,7 @@ flag, for example `docker build --no-cache`.
 See the [`Dockerfile` Best Practices
 guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for more information.
 
-The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
-[below](#add) for details.
+The cache for `RUN` instructions can be invalidated by [`ADD`](#add) and [`COPY`](#copy) instructions.
 
 ### Known issues (RUN)
 
@@ -1114,7 +1113,7 @@ does not support authentication.
 > following instructions from the Dockerfile if the contents of `<src>` have
 > changed. This includes invalidating the cache for `RUN` instructions.
 > See the [`Dockerfile` Best Practices
-guide](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+guide – Leverage build cache](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache)
 > for more information.
 
 
@@ -1304,6 +1303,15 @@ image with the same name is attempted to be used instead.
 - If `<dest>` doesn't exist, it is created along with all missing directories
   in its path.
   
+> **Note**
+>
+> The first encountered `COPY` instruction will invalidate the cache for all
+> following instructions from the Dockerfile if the contents of `<src>` have
+> changed. This includes invalidating the cache for `RUN` instructions.
+> See the [`Dockerfile` Best Practices
+guide – Leverage build cache](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache)
+> for more information.
+
 ## ENTRYPOINT
 
 ENTRYPOINT has two forms:

docs/reference/commandline/context_create.md

@@ -53,23 +53,30 @@ Options:
 Creates a new `context`. This allows you to quickly switch the cli
 configuration to connect to different clusters or single nodes.
 
+## Examples
+
+### Create a context with a docker and kubernetes endpoint
+
 To create a context from scratch provide the docker and, if required,
 kubernetes options. The example below creates the context `my-context`
 with a docker endpoint of `/var/run/docker.sock` and a kubernetes configuration
 sourced from the file `/home/me/my-kube-config`:
 
 ```bash
-$ docker context create my-context \
-      --docker host=/var/run/docker.sock \
-      --kubernetes config-file=/home/me/my-kube-config
+$ docker context create \
+    --docker host=unix:///var/run/docker.sock \
+    --kubernetes config-file=/home/me/my-kube-config \
+    my-context 
 ```
 
+### Create a context based on an existing context
+
 Use the `--from=<context-name>` option to create a new context from
 an existing context. The example below creates a new context named `my-context`
 from the existing context `existing-context`:
 
 ```bash
-$ docker context create my-context --from existing-context
+$ docker context create --from existing-context my-context 
 ```
 
 If the `--from` option is not set, the `context` is created from the current context:
@@ -92,9 +99,10 @@ the existing context `existing-context` and a kubernetes configuration sourced
 from the file `/home/me/my-kube-config`:
 
 ```bash
-$ docker context create my-context \
-      --docker from=existing-context \
-      --kubernetes config-file=/home/me/my-kube-config
+$ docker context create \
+    --docker from=existing-context \
+    --kubernetes config-file=/home/me/my-kube-config \
+    my-context
 ```
 
 To source only the `kubernetes` configuration from an existing context use the
@@ -103,10 +111,13 @@ context named `my-context` using the kuberentes configuration from the existing
 context `existing-context` and a docker endpoint of `/var/run/docker.sock`:
 
 ```bash
-$ docker context create my-context \
-      --docker host=/var/run/docker.sock \
-      --kubernetes from=existing-context
+$ docker context create \
+    --docker host=unix:///var/run/docker.sock \
+    --kubernetes from=existing-context \
+    my-context
 ```
 
 Docker and Kubernetes endpoints configurations, as well as default stack
-orchestrator and description can be modified with `docker context update`
+orchestrator and description can be modified with `docker context update`.
+
+Refer to the [`docker context update` reference](context_update.md) for details.

docs/reference/commandline/context_export.md

@@ -17,6 +17,7 @@ Options:
 
 ## Description
 
-Exports a context in a file that can then be used with `docker context import` (or with `kubectl` if `--kubeconfig` is set).
-Default output filename is `<CONTEXT>.dockercontext`, or `<CONTEXT>.kubeconfig` if `--kubeconfig` is set.
+Exports a context in a file that can then be used with `docker context import`
+(or with `kubectl` if `--kubeconfig` is set). Default output filename is
+`<CONTEXT>.dockercontext`, or `<CONTEXT>.kubeconfig` if `--kubeconfig` is set.
 To export to `STDOUT`, you can run `docker context export my-context -`.

docs/reference/commandline/context_import.md

@@ -14,4 +14,5 @@ Import a context from a tar file
 
 ## Description
 
-Imports a context previously exported with `docker context export`. To import from stdin, use a hyphen (`-`) as filename.
+Imports a context previously exported with `docker context export`. To import
+from stdin, use a hyphen (`-`) as filename.

docs/reference/commandline/context_inspect.md

@@ -27,34 +27,34 @@ Inspects one or more contexts.
 $ docker context inspect "local+aks"
 
 [
-    {
-        "Name": "local+aks",
-        "Metadata": {
-            "Description": "Local Docker Engine + Azure AKS endpoint",
-            "StackOrchestrator": "kubernetes"
-        },
-        "Endpoints": {
-            "docker": {
-                "Host": "npipe:////./pipe/docker_engine",
-                "SkipTLSVerify": false
-            },
-            "kubernetes": {
-                "Host": "https://simon-aks-***.hcp.uksouth.azmk8s.io:443",
-                "SkipTLSVerify": false,
-                "DefaultNamespace": "default"
-            }
-        },
-        "TLSMaterial": {
-            "kubernetes": [
-                "ca.pem",
-                "cert.pem",
-                "key.pem"
-            ]
-        },
-        "Storage": {
-            "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee",
-            "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee"
-        }
+  {
+    "Name": "local+aks",
+    "Metadata": {
+      "Description": "Local Docker Engine + Azure AKS endpoint",
+      "StackOrchestrator": "kubernetes"
+    },
+    "Endpoints": {
+      "docker": {
+        "Host": "npipe:////./pipe/docker_engine",
+        "SkipTLSVerify": false
+      },
+      "kubernetes": {
+        "Host": "https://simon-aks-***.hcp.uksouth.azmk8s.io:443",
+        "SkipTLSVerify": false,
+        "DefaultNamespace": "default"
+      }
+    },
+    "TLSMaterial": {
+      "kubernetes": [
+        "ca.pem",
+        "cert.pem",
+        "key.pem"
+      ]
+    },
+    "Storage": {
+      "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee",
+      "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee"
     }
+  }
 ]
 ```

docs/reference/commandline/context_ls.md

@@ -19,3 +19,15 @@ Options:
                         (default "table")
   -q, --quiet           Only show context names
 ```
+
+## Examples
+
+Use `docker context ls` to print all contexts. The currently active context is
+indicated with an `*`:
+
+```bash
+NAME                DESCRIPTION                               DOCKER ENDPOINT                      KUBERNETES ENDPOINT   ORCHESTRATOR
+default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                                swarm
+production                                                    tcp:///prod.corp.example.com:2376
+staging                                                       tcp:///stage.corp.example.com:2376
+```

docs/reference/commandline/context_update.md

@@ -48,4 +48,15 @@ Options:
 ## Description
 
 Updates an existing `context`.
-See [context create](context_create.md)
+See [context create](context_create.md).
+
+## Examples
+
+### Update an existing context
+
+```bash
+$ docker context update \
+    --description "some description" \
+    --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \
+    my-context
+```

docs/reference/commandline/context_use.md

@@ -13,5 +13,6 @@ Set the current docker context
 ```
 
 ## Description
-Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment variables and `--host`, `--context` global options are not set.
+Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment
+variables and `--host`, `--context` global options are not set.
 To disable usage of contexts, you can use the special `default` context.