From 3b76b2081b595857dc4dcf778e600f81f76d6291 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoshiki=20V=C3=A1zquez=20Baeza?= Date: Tue, 19 Jul 2016 10:28:59 -0700 Subject: [PATCH] DOC: Improve installation documentation This updates the INSTALL.md document to reflect the recent changes we've made, additionally it also removes the `installation_index.html`, and points any existing links to that document to INSTALL.md. --- INSTALL.md | 57 ++++++++++----- doc/description_index.html | 2 +- doc/index.html | 4 +- doc/installation_index.html | 138 ------------------------------------ doc/tutorial_index.html | 2 +- 5 files changed, 45 insertions(+), 158 deletions(-) delete mode 100644 doc/installation_index.html diff --git a/INSTALL.md b/INSTALL.md index 3a3969f8..83a726c7 100644 --- a/INSTALL.md +++ b/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]' +``` diff --git a/doc/description_index.html b/doc/description_index.html index e501ee37..15616bad 100644 --- a/doc/description_index.html +++ b/doc/description_index.html @@ -56,7 +56,7 @@
  • Description
  • Tutorial
    • -
  • Installation
    • +
  • Installation
  • Support
    • diff --git a/doc/index.html b/doc/index.html index dfdbfc82..9eec1f01 100644 --- a/doc/index.html +++ b/doc/index.html @@ -61,13 +61,13 @@
  • Description
  • Tutorial
    • -
  • Installation
    • +
  • Installation
  • Support
    • diff --git a/doc/installation_index.html b/doc/installation_index.html deleted file mode 100644 index bf058cd0..00000000 --- a/doc/installation_index.html +++ /dev/null @@ -1,138 +0,0 @@ - - - - - Emperor - - - - - - - - - - Fork me on GitHub - - - - - - - - - -
    - -
    -

    Emperor Logo

     - -
    - -

    Downloading

    -

    - Emperor is a python package hosted in GitHub that relies on NumPy, scikit-bio and qcli. These packages must be installed prior running the setup.py script. -

    -

    - - Download Stable Version - - - Download Development Version - -

    -
    -

    - To clone the git repository directly into your machine: -
    - 

    git clone git://github.com/biocore/emperor.git
    -

    -
    -

    Installing

    -

    - To perform a global installation of Emperor, execute the following command from a terminal session: -
    - 

    python setup.py install
    -

    -

    -
    - 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: -
    - 

    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/
    -
    -

    -

    - Alternatively Emperor can be installed from the Python Package Index (PyPi) using either conda (note that this method will be notably faster): -
    - 

    conda install scikit-bio
    pip install emperor
    -
    -

    -

    - or using pip: -
    - 

    pip install numpy
    pip install emperor
    -
    -

    Verifying your installation

    -

    - To test for a correct installation, open a new terminal window and issue the following command to see the help of make_emperor.py: - 

    make_emperor.py -h
-Usage: make_emperor.py [options] {-i/--input_coords INPUT_COORDS -m/--map_fp MAP_FP}
-
-[] indicates optional input (order unimportant)
-{} indicates required input (order unimportant)
-
-This script automates the creation  of three-dimensional PCoA plots to be visualized with Emperor using Google Chrome.
-
-Example usage: 
-Print help message and exit
- make_emperor.py -h
-
-...
-
    -

    -
    - -
    - -

    © The Emperor Development Team

    -     -
    - -
    - - diff --git a/doc/tutorial_index.html b/doc/tutorial_index.html index 2cf0f4de..91fd5ee4 100644 --- a/doc/tutorial_index.html +++ b/doc/tutorial_index.html @@ -56,7 +56,7 @@
  • Description
  • Tutorial
    • -
  • Installation
    • +
  • Installation
  • Support