Merge pull request #524 from ElDeveloper/better-docs

DOC: Improve installation documentation

INSTALL.md

@@ -1,31 +1,56 @@
 Emperor Installation Notes
 ==========================
 
-Emperor is a python package that relies in [QCLI](https://pypi.python.org/pypi/qcli) and [NumPy](http://www.numpy.org). These packages must be installed prior running the `setup.py` script.
+Emperor is a Python package that powers a JavaScript-based user interface. The
+Python library relies on several packages from the scientific Python stack.
 
-To download Emperor, use [this link](https://github.com/biocore/emperor/archive/master.zip) or use git to get the latest version of the repository:
+To install the latest release version of Emperor, you can use `pip` or
+`conda`:
 
-    git clone git://github.com/biocore/emperor.git
+```bash
+    # with pip
+    pip install emperor
+
+    # with conda
+    conda install -c bioconda emperor
+```
 
-Installation
+
+Pre-releases
 ============
 
-By far the easiest way to install Emperor is running:
+If you are interested in using a pre-release version (for example `1.0.0beta`)
+you can use `pip` or `conda`:
 
-    pip install emperor
+```bash
+    # with pip
+    pip install emperor --pre
 
-In other case, to perform a global installation of Emperor, execute the following command from a terminal session:
+    # with conda
+    conda install -c biocore emperor
+```
 
-    python setup.py install
+Note that we will update these pre-releases as often as it makes sense.
 
-If you do not want to do a global installation, you will have to add the Emperor scripts and libraries to the `PATH` and `PYTHONPATH` environment variables. To add these variables to your `.bash_profile` issue the following terminal commands:
+Developers
+==========
 
-``` bash
-echo "export PATH=$HOME/emperor_bin/:$PATH" >> ~/.bash_profile
-echo "export PYTHONPATH=$HOME/emperor_lib/:$PYTHONPATH" >> ~/.bash_profile
-python setup.py install --install-scripts=~/emperor_bin/ --install-purelib=~/emperor_lib/ --install-lib=~/emperor_lib/
-```
+If you are planning to do development, we recommend that you clone the git
+repository, create a new environment (using `conda` or `virtualenvs`) and then
+use `pip install -e` to work on the source code without having to reinstall
+when you make editions:
+
+```bash
+    # fork
+    git clone git://github.com/YOUR-USERNAME/emperor.git
 
-To test for a correct installation, open a new terminal window and issue the following command to see the help of `make_emperor.py`:
+    # if you are using conda
+    conda create -n emperor-dev scipy numpy pandas matplotlib jupyter
 
-    make_emperor.py -h
+    # if you are using virtualenvs
+    mkvirtualenv emperor-dev && workon emperor-dev
+
+    # now install the repository
+    cd emperor
+    pip install -e '.[all]'
+```

doc/description_index.html

@@ -56,7 +56,7 @@
                 </li>
                 <li class="active"><a href="#">Description</a></li>
                 <li><a href="tutorial_index.html">Tutorial</a></li>
-                <li><a href="installation_index.html">Installation</a></li>
+                <li><a href="https://github.com/biocore/emperor/blob/new-api/INSTALL.md#emperor-installation-notes">Installation</a></li>
                 <li><a href="https://github.com/biocore/emperor/issues">Support</a></li>
               </ul>
             </div>

doc/index.html

@@ -61,13 +61,13 @@
                 <li class="dropdown">
                   <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a>
                   <ul class="dropdown-menu">
-                    <li><a href="build/html/index.html">User Documentation</a></li>
+                    <li><a href="build/html/index.html">Python Documentation</a></li>
                     <li><a href="build/jsdoc/index.html">Javascript Documentation</a></li>
                   </ul>
                 </li>
                 <li><a href="description_index.html">Description</a></li>
                 <li><a href="tutorial_index.html">Tutorial</a></li>
-                <li><a href="installation_index.html">Installation</a></li>
+                <li><a href="https://github.com/biocore/emperor/blob/new-api/INSTALL.md#emperor-installation-notes">Installation</a></li>
                 <li><a href="https://github.com/biocore/emperor/issues">Support</a></li>
               </ul>
             </div>

doc/tutorial_index.html

@@ -56,7 +56,7 @@
                 </li>
                 <li><a href="description_index.html">Description</a></li>
                 <li class="active"><a href="#">Tutorial</a></li>
-                <li><a href="installation_index.html">Installation</a></li>
+                <li><a href="https://github.com/biocore/emperor/blob/new-api/INSTALL.md#emperor-installation-notes">Installation</a></li>
                 <li><a href="https://github.com/biocore/emperor/issues">Support</a></li>
               </ul>
             </div>