From d08506ae12fe1d9949b5bd473845cfaa0e6f242d Mon Sep 17 00:00:00 2001
From: bkmartinjr <bruce@chanzuckerberg.com>
Date: Sat, 9 Nov 2019 12:49:22 -0800
Subject: [PATCH] improve install docs

---
 docs/posts/install.md | 70 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 18 deletions(-)

diff --git a/docs/posts/install.md b/docs/posts/install.md
index 0f0c892c..7aeeae86 100644
--- a/docs/posts/install.md
+++ b/docs/posts/install.md
@@ -3,38 +3,62 @@ title: Install
 subtitle: Install
 layout: default
 ---
+
 # Installing cellxgene
 
 Cellxgene has two parts:
-* [`cellxgene`](launch) is the main explorer application, which takes an already-processed `h5ad` file as input. This is installed by default.  
-* [`cellxgene prepare`](prepare) provides auxiliary functionality for preparing your dataset. This is *not* installed by default.
 
-## Requirements  
-You'll need **python 3.6+** and **Google Chrome**.
+- [`cellxgene`](launch) is the main explorer application, which takes an already-processed `h5ad` file as input. This is installed by default.
+- [`cellxgene prepare`](prepare) provides auxiliary functionality for preparing your dataset. This is _not_ installed by default.
+
+## Requirements
+
+You'll need **python 3.6+** and an up-to-date version of **Google Chrome**.
 The web UI is tested on OSX and Windows using Chrome, and the python CLI is tested on OSX and Ubuntu (via WSL/Windows).
 It should work on other platforms, but if you run into trouble let us know.
 
-## Basic install  
-To install `cellxgene` alone, run:  
-`pip install cellxgene`
+[Python.org](https://www.python.org/downloads/) has help on installing a recent
+version of Python, including the pip package manager. Chrome is available at
+[Google.com/chrome](https://google.com/chrome).
 
-To install `cellxgene` and the optional `cellxgene prepare`, run:  
-`pip install cellxgene[prepare]`
+## Basic install using pip
+
+To install the `cellxgene` explorer alone, run:
+
+```
+pip install cellxgene
+```
+
+To install `cellxgene` and the optional `cellxgene prepare`, run:
+
+```
+pip install cellxgene[prepare]
+```
+
+_Note: if the aforementioned optional `prepare` package installation fails, you can also install these packages directly:_
 
-_Note: if the aforementioned optional `prepare` package installation fails, you can also install these packages directly:_  
 ```
 pip install scanpy>=1.3.7 python-igraph louvain>=0.6
 ```
 
+If you already have `cellxgene` installed, you can update to the most recent version by running:
+
+```
+pip install cellxgene --upgrade
+```
+
 ## Using a conda environment
-To install `cellxgene` alone, run:  
+
+To install `cellxgene` alone, run:
+
 ```
 conda create --yes -n cellxgene python=3.7
 conda activate cellxgene
 pip install cellxgene
 ```
 
-To install `cellxgene` and the optional `cellxgene prepare`, run:  
+To install `cellxgene` and the optional `cellxgene prepare`, run:
+
 ```
 conda create --yes -n cellxgene python=3.7
 conda activate cellxgene
@@ -42,7 +66,9 @@ pip install cellxgene[prepare]
 ```
 
 ## Using a virtual environment
-To install `cellxgene` alone, run:  
+
+To install `cellxgene` alone, run:
+
 ```
 ENV_NAME=cellxgene
 python3.7 -m venv ${ENV_NAME}
@@ -50,7 +76,8 @@ source ${ENV_NAME}/bin/activate
 pip install cellxgene
 ```
 
-To install `cellxgene` and `cellxgene prepare`, run:  
+To install `cellxgene` and `cellxgene prepare`, run:
+
 ```
 ENV_NAME=cellxgene
 python3.7 -m venv ${ENV_NAME}
@@ -59,10 +86,17 @@ pip install cellxgene[prepare]
 ```
 
 ## Using docker
-Build the image  
-`docker build . -t cellxgene`
 
-Run the container and mount data  
-`docker run -v "$PWD/example-dataset/:/data/" -p 5005:5005 cellxgene launch --host 0.0.0.0 data/pbmc3k.h5ad`
+Build the image
+
+```
+docker build . -t cellxgene
+```
+
+Run the container and mount data (change data location, `--port` and `--host` parameters as needed)
+
+```
+docker run -v "$PWD/example-dataset/:/data/" -p 5005:5005 cellxgene launch --host 0.0.0.0 data/pbmc3k.h5ad
+```
 
 You will need to use `--host 0.0.0.0` to have the container listen to incoming requests from the browser