[containers] Updated docs, added comments per PR

Author: eshvk

Dockerfile

@@ -116,8 +116,6 @@ RUN set -ex; \
 		\) -exec rm -rf '{}' +; \
 	rm -f get-pip.py
 
-CMD ["python3"]
-
 
 RUN apt-get update && apt-get -y upgrade
 

README.md

@@ -27,7 +27,7 @@ to the wider research and game developer communities.
 * Built-in support for Imitation Learning
 * Flexible Agent control with On Demand Decision Making
 * Visualizing network outputs within the environment
-* Simplified set-up with Docker (Experimental)
+* Simplified set-up with Docker
 
 ## Documentation and References
 

docs/ML-Agents-Overview.md

@@ -428,8 +428,7 @@ the broadcasting feature
 * **Docker Set-up (Experimental)** - To facilitate setting up ML-Agents
 without installing Python or TensorFlow directly, we provide a 
 [guide](Using-Docker.md) on how
-to create and run a Docker container. Due to limitations on rendering visual
-observations, this feature is marked experimental.
+to create and run a Docker container.
 
 * **Cloud Training on AWS** - To facilitate using ML-Agents on
 Amazon Web Services (AWS) machines, we provide a 

docs/Using-Docker.md

@@ -1,6 +1,6 @@
 # Using Docker For ML-Agents (Experimental)
 
-We currently offer a solution for Windows and Mac users who would like to do training or inference using Docker. This option may be appealing to those who would like to avoid installing Python and TensorFlow themselves. The current setup forces both TensorFlow and Unity to _only_ rely on the CPU for computations. Consequently, our Docker simulation [uses the CPU](https://en.wikipedia.org/wiki/Xvfb) to do visual rendering. This means that environments which involve agents using camera-based visual observations might be slower.
+We currently offer a solution for Windows and Mac users who would like to do training or inference using Docker. This option may be appealing to those who would like to avoid installing Python and TensorFlow themselves. The current setup forces both TensorFlow and Unity to _only_ rely on the CPU for computations. Consequently, our Docker simulation [does not use a GPU](https://en.wikipedia.org/wiki/Xvfb) to do visual rendering. This means that rich environments which involve agents using camera-based visual observations might be slower.
 
 
 ## Requirements
@@ -28,10 +28,15 @@ Unity environment **has** to be built for the **linux platform**. When building
 - Set the _Target Platform_ to `Linux`
 - Set the _Architecture_ to `x86_64`
 
-![Build Settings For Docker](images/docker_build_settings.png)
+![Build Settings For Docker](images/docker_build_settings_noheadless.png)
 
 Then click `Build`, pick an environment name (e.g. `3DBall`) and set the output directory to `unity-volume`. After building, ensure that the file `<environment-name>.x86_64` and subdirectory `<environment-name>_Data/` are created under `unity-volume`.
 
+**NOTE** If you are only collecting vector observations from Unity, you can select the `headless` option here:
+
+![Build Settings For Docker](images/docker_build_settings_headless.png)
+
+
 ### Build the Docker Container
 
 First, make sure the Docker engine is running on your machine. Then build the Docker container by calling the following command at the top-level of the repository:

docs/images/docker_build_settings.png renamed to docs/images/docker_build_settings_headless.png

@@ -102,6 +102,23 @@ def __init__(self, file_name, worker_id=0,
                      '--port', str(self.port),
                      '--seed', str(seed)])
             else:
+                """
+                Comments for future maintenance:
+                    xvfb-run is a wrapper around Xvfb, a virtual xserver where all
+                    rendering is done to virtual memory. It automatically creates a
+                    new virtual server automatically picking a server number `auto-servernum`.
+                    The server is passed the arguments using `server-args`, we are telling
+                    Xvfb to create Screen number 0 with width 640, height 480 and depth 24 bits.
+                    Note that 640 X 480 are the default width and height. The main reason for
+                    us to add this is because we'd like to change the depth from the default
+                    of 8 bits to 24.
+                    Unfortunately, this means that we will need to pass the arguments through
+                    a shell which is why we set `shell=True`. Now, this adds its own
+                    complications. E.g SIGINT can bounce off the shell and not get propagated
+                    to the child processes. This is why we add `exec`, so that the shell gets
+                    launched, the arguments are passed to `xvfb-run`. `exec` replaces the shell
+                    we created with `xvfb`.
+                """
                 docker_ls = ("exec xvfb-run --auto-servernum"
                              " --server-args='-screen 0 640x480x24'"
                              " {0} --port {1} --seed {2}").format(launch_string,