Add conda installation instructions

Jürgen Knödlseder
1 parent 45ad9a3b
Showing 3 changed files with 88 additions and 15 deletions
doc/source/admin/index.rst
doc/source/admin/install_conda.rst
doc/source/admin/install.rst → doc/source/admin/install_source.rst
@@ -6,6 +6,7 @@ Getting ctools
 .. toctree::
    :maxdepth: 1
+   install_source
+   install_conda
    download
-   install
    release_history/index
+.. _sec_install_conda:
+
+Installing via conda
+====================
+
+`Anaconda <https://www.anaconda.com/download/>`_ (you can also use
+`Miniconda <https://conda.io/miniconda.html>`_ for a smaller footprint) is a
+scientific Python installation shipping with essentially all needed packages.
+Install it according to the instructions on their homepage. You can use any
+Anaconda Python version. An Anaconda Python installation is completely separate
+from any existing system wide or user space Python installation, so Anaconda
+can be tested without the fear of breaking an existing installation.
+
+Anaconda works on most systems without root access!
+
+
+Installing
+----------
+
+- `Install Anaconda following the instructions on their site <https://www.anaconda.com/download/>`_
+
+- Add the ``conda-forge`` and ``cta-observatory`` channels to your Anaconda
+  configuration
+
+  .. code-block:: bash
+
+     $ conda config --append channels conda-forge
+     $ conda config --append channels cta-observatory
+
+- We strongly recommend to work with separate Anaconda environments, and
+  especially not use the special root environment (that is used for all conda
+  commands and environment manipulations, package installations etc.) for
+  anything besides updating the conda package itself (if necessary):
+
+  .. code-block:: bash
+
+     $ conda create -n myenv python=2.7  # or e.g. python=3.5
+     $ source activate myenv
+     (myenv) $
+
+- Install pre-compiled ctools conda package from Anaconda cloud with:
+
+  .. code-block:: bash
+
+     (myenv) $ conda install ctools
+
+  This will also install the required dependencies, and in particular GammaLib
+  and cfitsio.
+
+- Re-activate your environment to initialise the ctools environment variables
+
+  .. code-block:: bash
+
+     (myenv) $ source activate myenv
+
+
+Testing
+-------
+
+Type the following to test the ctools and GammaLib packages
+
+.. code-block:: bash
+
+   (myenv) $ python -c 'import ctools; ctools.test()'
+   (myenv) $ python -c 'import cscripts; cscripts.test()'
+   (myenv) $ python -c 'import gammalib; gammalib.test()'
+
+
+Updating
+--------
+
+Type the following to update the ctools package
+
+.. code-block:: bash
+
+   (myenv) $ conda update ctools
+
+or (if you did not add the ``cta-observatory`` channel to your default
+channels):
+
+.. code-block:: bash
+
+   (myenv) $ conda update -c cta-observatory ctools
-.. _sec_install:
+.. _sec_compiling_source:
-Installing ctools
-=================
+Compiling from source
+=====================
 Before you start
 ----------------
@@ -27,8 +27,6 @@ software:
 No system administrator privileges are needed to install ctools.
-.. _sec_installing_gammalib:
-
 Installing GammaLib
 -------------------
@@ -97,8 +95,6 @@ which then installs GammaLib in the ``gamma`` folder of your home
 directory.
-.. _sec_setup_gammalib:
-
 Setting up the GammaLib environment
 -----------------------------------
@@ -161,8 +157,6 @@ You can get the full list of configuration options by typing
   $ ./configure --help
-.. _sec_testing_ctools:
-
 Testing ctools
 --------------
@@ -249,7 +243,6 @@ first the :ref:`issues` section. If you cannot fix the problem, please
 create an issue on the ctools tracker
 `here <https://cta-redmine.irap.omp.eu/projects/ctools>`_.
-.. _sec_installing_ctools:
 Installing ctools
 -----------------
@@ -277,7 +270,6 @@ can be given, for example:
   $ ./configure --prefix=$HOME/gamma
-.. _sec_setup_ctools:
 Setting up the ctools environment
 ---------------------------------
@@ -302,7 +294,6 @@ If you use C shell or a variant then add the following to your
   setenv CTOOLS /usr/local/gamma
   source $CTOOLS/bin/ctools-init.csh
-.. _sec_check_ctools_setup:
 Checking your setup
 -------------------
@@ -330,8 +321,6 @@ detailed information about your setup. There&#39;s also a ``csinfo list``
 command to quickly list the available tools.
-.. _sec_known_problems:
-
 Known problems
 --------------