Documentation about automatic bind-mount dir creation

Docker-DCO-1.1-Signed-off-by: Maxime Petazzoni <max@signalfuse.com> (github: mpetazzoni)

docs/sources/reference/commandline/cli.rst

@@ -1098,6 +1098,15 @@ working directory, by changing into the directory to the value
 returned by ``pwd``. So this combination executes the command
 using the container, but inside the current working directory.
 
+.. code-block:: bash
+
+    $ sudo docker run -v /dont/exist:/foo -w /foo -i -t ubuntu bash
+
+When the host directory of a bind-mounted volume doesn't exist, Docker
+will automatically create this directory on the host for you. In the
+example above, Docker will create the ``/dont/exist`` folder before
+starting your container.
+
 .. code-block:: bash
 
     $ sudo docker run -p 127.0.0.1:80:8080 ubuntu bash

docs/sources/use/working_with_volumes.rst

@@ -89,11 +89,15 @@ Mount a Host Directory as a Container Volume:
 ::
 
   -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
-  If "host-dir" is missing, then docker creates a new volume.
 
-This is not available from a Dockerfile as it makes the built image less portable
-or shareable. [host-dir] volumes are 100% host dependent and will break on any 
-other machine.
+If ``host-dir`` is missing from the command, then docker creates a new volume.
+If ``host-dir`` is present but points to a non-existent directory on the host,
+Docker will automatically create this directory and use it as the source of the
+bind-mount.
+
+Note that this is not available from a Dockerfile due the portability and
+sharing purpose of it. The ``host-dir`` volumes are entirely host-dependent and
+might not work on any other machine.
 
 For example::