Merge pull request #2501 from thaJeztah/fix_context_reference

docs: fix, and touch-up "docker context" docs

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 context create \
-      --docker host=/var/run/docker.sock \
+    --docker host=unix:///var/run/docker.sock \
-      --kubernetes config-file=/home/me/my-kube-config
+    --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 context create \
     --docker from=existing-context \
-      --kubernetes config-file=/home/me/my-kube-config
+    --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 context create \
-      --docker host=/var/run/docker.sock \
+    --docker host=unix:///var/run/docker.sock \
-      --kubernetes from=existing-context
+    --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).
+Exports a context in a file that can then be used with `docker context import`
-Default output filename is `<CONTEXT>.dockercontext`, or `<CONTEXT>.kubeconfig` if `--kubeconfig` is set.
+(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_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.