Merge pull request #1 from jonbruner/master

Refactor Readme

Author: raulpuric

README.md

@@ -1,24 +1,75 @@
 # Caption This!
+
 This repository contains source code corresponding to our article ["Caption this, with TensorFlow!"]( https://www.oreilly.com/learning/caption-this-with-tensorflow) (publishing soon check out our [article preprint](https://github.com/mlberkeley/oreilly-captions/blob/master/article-preprint.pdf) for now).
 
+
 # Git Basics
-1. Go to your home directory with just a `cd` command
-2. Clone the repository with `git clone https://github.com/mlberkeley/oreilly-captions.git`
+1. Go to your home directory by opening your terminal and entering `cd ~`
+
+2. Clone the repository by entering
+
+    ```
+    git clone https://github.com/mlberkeley/oreilly-captions.git
+    ```
+
+# Docker (highly recommended)
+Install Docker using the platform-specific installation instructions for Docker [here](https://docs.docker.com/engine/installation/#platform-support-matrix). Our iPython notebooks are compatible with TensorFlow 1.0.
+
+### Option A: Use our pre-built Docker image from Docker Hub
+
+3. After installing Docker, pull a prebuilt image from our Docker Hub by entering:
+
+    ```
+    docker pull mlatberkeley/showandtell
+    ```
+
+    You will need a Docker Hub account in order to pull the image (get one [here](https://hub.docker.com/)). If it's your first time pulling a Docker image from Docker Hub you will need to login to your Docker Hub account from your terminal with `docker login`, and follow the username and password prompt.
+
+4. To run the pulled image (after cloning and downloading the repository) enter
+
+    ```
+    docker run -it -p 8888:8888 -v <path to repo>:/root mlatberkeley/showandtell
+    ```
+
+    where `<path to repo>` should be the __absolute path__ to your cloned repository. If you followed our **Git Basics** section the path should be `<path to your home directory>/oreilly-captions`.
+
+5. After building, starting, and attaching to the appropriate Docker container, run the provided Jupyter notebooks by entering
+
+    ```
+    jupyter notebook --ip 0.0.0.0
+    ```
+
+    and navigate to [http://0.0.0.0:8888](http://0.0.0.0:8888) in your browser.
+
+### Option B: Download and build your own Docker image from our GitHub repo
+If you want to build a GPU or CPU-based Docker image of your own, you can use the Dockerfiles provided in the `/dockerfiles/` subdirectory of our GitHub repo.
+
+3. After cloning the repo to your machine, enter
+
+    ```
+    docker build -t <image_name> ./dockerfiles/
+    ```
+
+    where `<image_name>` is either `gpu` or `cpu`. (Note that, in order to run these files on your GPU, you'll need to have a compatible GPU, with drivers installed and configured properly [as described in TensorFlow's documentation](https://www.tensorflow.org/install/).)
+
+4. Run the Docker image by entering
 
-# Docker
-**Running with Docker is highly recommended**
-You can find platform-specific installation instructions for Docker [here](https://docs.docker.com/engine/installation/#platform-support-matrix). Our iPython notebooks are compatible with TensorFlow 1.0.
+    ```
+    docker run -it -p 8888:8888 -v <path to repo>:/root <image_name>
+    ```
 
-(*Recommended*) After installing Docker, pull a prebuilt image from our dockerhub with `docker pull mlatberkeley/showandtell`. You will need a dockerhub account in order to pull the image (get one [here](https://hub.docker.com/)). If it's your first time pulling a docker image from dockerhub you will need to login to your dockerhub account from your terminal with `docker login`, and follow the username/password prompt onscreen.
+    where `<image_name>` is either `gpu` or `cpu`, depending on the image you built in the last step.
 
-(We have however provided Dockerfiles in `./dockerfiles/` if the user would like to build a gpu or cpu-based docker image with `docker build -t <image_name> ./dockerfiles/`)
+5. After building, starting, and attaching to the appropriate Docker container, run the provided Jupyter notebooks by entering
 
-To run the pulled image (after cloning and downloading the repository) use `docker run -it -p 8888:8888 -v <path to repo>:/root mlatberkeley/showandtell`. `<path to repo>` Should be the __absolute path__ to your cloned repository. If you followed our **Git Basics** section the path should be `<path to your home directory>/oreilly-captions`. (Substitute `mlatberkeley/showandtell` with the name of the docker image you built if you built your image using the Dockerfiles in `./dockerfiles`) 
+    ```
+    jupyter notebook --ip 0.0.0.0
+    ```
 
-After building, starting, and attaching to the appropriate Docker container, run the provided jupyter notebooks with `jupyter notebook --ip 0.0.0.0` and follow the instructions on screen.
+    and navigate to [http://0.0.0.0:8888](http://0.0.0.0:8888) in your browser.
 
 **Note**
-If you are using Docker Toolbox as opposed to native Docker you will have to navigate to the Daemon IP adress (instead of 0.0.0.0) provided right after starting the Docker Quickstart Terminal (for us this was 192.168.99.100) in order to use jupyter.
+If you are using Docker Toolbox as opposed to native Docker you will have to navigate to the Daemon IP adress (instead of 0.0.0.0) provided right after starting the Docker Quickstart Terminal (for us this was 192.168.99.100) in order to use Jupyter.
 
 ### Debugging docker
 If you receive an error of the form:
@@ -28,7 +79,7 @@ WARNING: Error loading config file:/home/rp/.docker/config.json - stat /home/rp/
 Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.26/images/json: dial unix /var/run/docker.sock: connect: permission denied
 ```
 
-It's most likely because you installed docker using sudo permissions with a packet manager such as `brew` or `apt-get`. To solve this `permission denied` simply run docker with `sudo` (ie. run `docker` commands with `sudo docker <command and options>` instead of just `docker <command and options>`). 
+It's most likely because you installed Docker using sudo permissions with a packet manager such as `brew` or `apt-get`. To solve this `permission denied` simply run docker with `sudo` (ie. run `docker` commands with `sudo docker <command and options>` instead of just `docker <command and options>`).
 
 # The Notebooks
 There are three notebooks:
@@ -42,6 +93,6 @@ In order to run the first two notebooks, you will need VGG-16 image embeddings f
 
 Additionally, you will need the corresponding captions for these images (`results_20130124.token`), which can also be downloaded from our [Google Drive](https://drive.google.com/file/d/0B2vTU3h54lTydXFjSVM5T2t4WmM/view?usp=sharing).
 
-In order to run the `3. O'Reilly Generate from image.ipynb` notebook you will need to download a pretrained TensorFlow model for [VGG-16](https://drive.google.com/file/d/0B2vTU3h54lTyaDczbFhsZFpsUGs/view?usp=sharing) generated from the original Caffe model from the VGG-16 paper. 
+In order to run the `3. O'Reilly Generate from image.ipynb` notebook you will need to download a pretrained TensorFlow model for [VGG-16](https://drive.google.com/file/d/0B2vTU3h54lTyaDczbFhsZFpsUGs/view?usp=sharing) generated from the original Caffe model from the VGG-16 paper.
 
-Place all of these downloads in the `./data/` folder.
+Place all of these downloads in the `./data/` directory.