Overhaul our README file

Author: rosbo

README.md

@@ -1,60 +1,62 @@
-**Kaggle Kernels** allow users to run scripts against our competitions and datasets without having to download data or set up their environment. Here's [an example](https://www.kaggle.com/devinanzelmo/d/devinanzelmo/dota-2-matches/setting-up-a-prediction-problem-dota-2):
+[Kaggle Kernels](https://www.kaggle.com/kernels) allow users to run a Python Notebook in the cloud against our competitions and datasets without having to download data or set up their environment.
 
-![example script](http://i.imgur.com/yrWycNA.png)
+This repository includes our Dockerfiles for building the [CPU-only](Dockerfile) and [GPU](gpu.Dockerfile) image that runs Python Kernels on Kaggle. 
 
-This is the Dockerfile (etc.) used for building the image that runs python scripts on Kaggle. [Here's](https://gcr.io/kaggle-images/python) the Docker image on Google Container Registry.
+Our Python Docker images are stored on Google Container Registry at:
+
+* CPU-only: [gcr.io/kaggle-images/python](https://gcr.io/kaggle-images/python)
+* GPU: private for now, we will make it public soon.
+
+Note: The base image for the GPU image is our CPU-only image. The [gpu.Dockerfile](gpu.Dockerfile) adds a few extra layers to install GPU related libraries and packages (cuda, libcudnn, pycuda etc.) and reinstall packages with specific GPU builds (torch, tensorflow and a few mores).
 
 ## Getting started
 
 To get started with this image, read our [guide](http://blog.kaggle.com/2016/02/05/how-to-get-started-with-data-science-in-containers/) to using it yourself, or browse [Kaggle Kernels](https://www.kaggle.com/kernels) for ideas.
 
-## Requesting new features
+## Requesting new packages
 
-**We welcome pull requests** if there are any packages you'd like to add!
+First, evaluate whether installing the package yourself in your own Kernels suits your needs. See [guide](wiki/Missing-Packages).
 
-We can merge your request quickly if you check that it builds correctly. Here's how to do that.
+If you the first step above doesn't work for your use case, [open an issue](https://github.com/Kaggle/docker-python/issues/new) or a [pull request](https://github.com/Kaggle/docker-python/pulls).
 
-Start by running this image on your system:
+## Opening a pull request
 
-```
-me@my-computer:/home$ docker run --rm -it gcr.io/kaggle-images/python
-root@d72b81a003e1:/# 
-```
+1. Update the *Dockerfile*
+  1. For changes specific to the GPU image, update the [gpu.Dockerfile](gpu.Dockerfile).
+  2. Otherwise, update the [Dockerfile](Dockerfile).
+2. Follow the instructions below to build a new image.
+3. Add tests for your new package. See this [example](https://github.com/Kaggle/docker-python/blob/master/tests/test_fastai.py).
+4. Follow the instructions below to test the new image.
+5. Open a PR on this repo and you are all set!
 
-Then follow the package's installation instructions for a Linux system. It could be as simple as installing via Pip:
+## Building a new image
 
-```
-root@d72b81a003e1:/# pip install coolpackage
-Collecting coolpackage
-[...etc...]
+```sh
+./build
 ```
 
-Once that's done, check that you can import it correctly. (Sometimes, if a package is missing a dependency, it throws an error when you try to import it.)
+Flags:
 
-```
-root@d72b81a003e1:/# python
-Python 3.5.2 |Anaconda 4.2.0 (64-bit)| (default, Jul  2 2016, 17:53:06)
-[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)] on linux
-Type "help", "copyright", "credits" or "license" for more information.
->>> import coolpackage
->>>
-```
+* `--gpu` to build an image for GPU.
+* `--use-cache` for faster iterative builds.
 
-Once that's working, add the necessary lines to our [Dockerfile](https://github.com/Kaggle/docker-python/blob/master/Dockerfile). (In this case, that would mean adding `pip install coolpackage` to the last section.)
+## Testing a new image
 
-Next run the build:
+A suite of tests can be found under the `/tests` folder. You can run the test using this command:
 
-```
-./build
+```sh
+./test
 ```
 
-Finally run the tests:
+Flags:
 
-```
-./test
-```
+* `--gpu` to test the GPU image.
 
-Then submit your pull request, and you're all set!
+## Tensorflow custom pre-built wheels
 
+We are building Tensorflow from sources mainly for:
 
+* Better performance. When building from sources, we can leverage CPU specific optimizations
+* Tensorflow with GPU support must be built from sources
 
+The [Dockerfile](tensorflow-whl/Dockerfile) and the [instructions](tensorflow-whl/README.md) can be found in the [tensorflow-whl folder/](tensorflow/).