Updated/simplified installation instructions, and advocate for mamba.…

… Recommend installing from conda-forge rather than glueviz channel.

doc/customizing_guide/available_plugins.rst

@@ -31,7 +31,7 @@ plugin is installed, you should see the 3D viewers in the list:
 If you don't see these in the list, then, you can install the 3D viewers plugin
 using::
 
-    conda install -c glueviz glue-vispy-viewers
+    mamba install -c conda-forge glue-vispy-viewers
 
 or if you don't use conda::
 
@@ -56,7 +56,7 @@ We are currently developing a plugin to make it easy to export plots made in
 glue to standalone interactive figures using `plotly <https://plot.ly/>`_. If
 you are interested in trying this out, you can install it with::
 
-    conda install -c glueviz glue-plotly
+    mamba install -c conda-forge glue-plotly
 
 or if you don't use conda::
 
@@ -86,7 +86,7 @@ this to other formats and as well as other functionality (e.g. colormaps) that
 would be useful in medical imaging. You can install the current version of this
 plugin with::
 
-    conda install -c glueviz glue-medical
+    mamba install -c conda-forge glue-medical
 
 or if you don't use conda::
 
@@ -112,7 +112,7 @@ plugin tries to automatically set up the coordinate system for the datasets so
 that you can link datasets based on longitude/latitude. You can install the
 current version of this plugin with::
 
-    conda install -c glueviz glue-geospatial
+    mamba install -c conda-forge glue-geospatial
 
 or if you don't use conda::
 
@@ -141,7 +141,7 @@ The **glue-wwt** adds a data viewer to glue that allows users to overplot data
 onto maps of the sky, powered by `WorldWide Telescope
 <http://worldwidetelescope.org/webclient/>`_. You can install this plugin with::
 
-    conda install -c glueviz glue-wwt
+    mamba install -c conda-forge glue-wwt
 
 or if you don't use conda::
 
@@ -180,7 +180,7 @@ Application Messaging Protocol (SAMP) - these include for example `DS9
 <https://aladin.u-strasbg.fr/>`_. The **glue-samp** plugin adds the ability to
 use SAMP from glue.  You can install this plugin with::
 
-    conda install -c glueviz glue-samp
+    mamba install -c conda-forge glue-samp
 
 or if you don't use conda::
 

doc/gui_guide/3d_viewers.rst

@@ -18,7 +18,7 @@ If you don't see these in the list, then if you are using
 `Anaconda <https://www.anaconda.com/distribution/>`_ to manage your Python
 distribution, you can install the 3D viewers plugin using::
 
-    conda install -c glueviz glue-vispy-viewers
+    mamba install -c conda-forge glue-vispy-viewers
 
 With the plugin installed, you will now have access to two new data
 viewers in Glue:

doc/installation/conda.rst

@@ -1,112 +1,62 @@
-
-Anaconda Python distribution
-============================
+Installing with conda
+=====================
 
 **Platforms:** MacOS X, Linux, and Windows
 
-We recommend using the `Anaconda <https://www.anaconda.com/distribution/>`__ Python
-distribution from Continuum Analytics (or the related `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ distribution).
-Anaconda includes all of Glue's main dependencies. There are two ways of
-installing Glue with the Anaconda Python Distribution: :ref:`graphically using the
-Anaconda Navigator <anaconda_gui>`, or :ref:`using the conda command
-<anaconda_cli>` on the command-line, both of which are described
-below.
-
-.. _anaconda_cli:
-
-Command-line installation
--------------------------
-
-Once Anaconda (or Miniconda) is installed, we recommend installing glue using
-the ``conda`` command on the command-line rather than using the
-:ref:`anaconda_gui`, because errors are more visible on the command-line if you
-run into any issues during the installation.
-
-First, make sure that your conda command is up to date::
-
-    conda update -n root conda
-
-then install glue with::
-
-    conda install -c glueviz glueviz=1.2
-
-This will install the latest version of glue from the ``glueviz`` conda channel.
-
-If you run into any issues, even after having updated ``conda``, see the
-`Troubleshooting`_ section below. To update glue in future, use the same install
-command as above.
-
-.. _anaconda_gui:
+Because glue is a reasonably big package with a number of dependencies, we have
+found that the default ``conda`` command included in Anaconda/Miniconda can run
+into issues when trying to solve the dependencies, so we highly recommend making use
+of the `mamba <https://mamba.readthedocs.io/en/latest/>`_ tool to install glue. We have
+provided separate instructions below for new and existing conda users.
 
-Graphical User Interface
-------------------------
+New conda user
+--------------
 
-If you prefer to not use the command-line to install glue, you can also use the
-Anaconda navigator, but be aware that it is harder to diagnose issues when
-things go wrong (the navigator can sometimes silently fail). Once Anaconda is
-installed, go to the **Applications** folder and launch the **Anaconda
-Navigator**:
+If you have never used conda before, we recommend downloading the **Mambaforge**
+distribution from https://conda-forge.org/miniforge/. For Windows users, you can
+download and install using an ``.exe`` installer. For Linux and MacOS X you
+should download the appropriate ``.sh`` file and install it using::
 
-.. image:: images/navigator_icon.png
-   :align: center
-   :width: 80
+    bash MambaForge-*.sh
 
-If you do not have the Anaconda Navigator icon, but have an Anaconda Launcher,
-you are using an old version of Anaconda, and we recommend that you update to
-the latest version.
+Once installed, we recommend you create a new environment to install glue in using::
 
-Assuming you have the navigator open, before installing glue first click on the
-**Channels** button:
+    mamba create -n glue-env
 
-.. image:: images/navigator_channels_button.png
-   :align: center
-   :width: 373
+You can then switch to this environment using::
 
-If not already present, add **glueviz** to the list of channels by clicking
-on **Add**, typing **glueviz**, and pressing enter, then click on **Update
-channels**:
+    mamba activate glue-env
 
-.. image:: images/navigator_channels_dialog.png
-   :align: center
-   :width: 414
+and install glue with::
 
-You can now install the latest version of glue by clicking on **Install**:
+    mamba install glueviz
 
-.. image:: images/navigator_install.png
-   :align: center
-   :width: 264
+Existing conda user
+-------------------
 
-Once the installation is complete, you can click on the **Launch** button (which
-will replace the **Install** button). If updates become available in future,
-these should be shown in the Navigator.
+If you already use the `Anaconda <https://www.anaconda.com/distribution/>`__ Python
+distribution from Continuum Analytics or the related `Miniconda
+<https://docs.conda.io/en/latest/miniconda.html>`__ distribution, we recommend first
+installing ``mamba`` using::
 
-Troubleshooting
----------------
+    conda install -c conda-forge mamba
 
-If you managed to install glue but it does not launch or you have issues with
-viewers not being available or not working correctly, the first thing to try
-is to update all your existing conda packages using::
+Once installed, we recommend you create a new environment to install glue in using::
 
-    conda update -c glueviz --all
+    mamba create -n glue-env
 
-In some cases, glue won't even install due to conflicts between the version of
-dependencies required by glue and that required by other packages. The easiest
-way to avoid this is to install glue in a separate environment. To do this,
-first create an environment in which you will install glue::
+You can then switch to this environment using::
 
-    conda create -n glueviz-env python
+    mamba activate glue-env
 
-This will create an environment called ``glueviz`` in which Python will be
-installed. You only need to create the environment once. Once created, you can
-switch to the environment with::
+and install glue with::
 
-    source activate glueviz-env
+    mamba install -c conda-forge glueviz
 
-Then, install glue as indicated in :ref:`anaconda_cli` using::
+Updating glue
+-------------
 
-    conda install -c glueviz glueviz
+To update the packages in your ``glue-env`` environment to the latest available
+versions, you can do::
 
-Whenever you open a new terminal, if you want to run glue you should then
-remember to switch to the ``glueviz-env`` environment using the ``source
-activate`` command above. If you want to update glue, run the installation
-command again inside the environment.
+    mamba update -c conda-forge --all

doc/installation/developer.rst

@@ -4,103 +4,18 @@ Installing the latest developer version
 .. note:: The latest developer version is not guaranteed to work correctly
           or be functional at all, so use with care!
 
-With conda
-----------
+If you normally use conda or pip to install glue and want to try out the
+latest developer version, the recommended way is to use pip to install
+packages from the git repository directly.
 
-If you use Anaconda/conda to install glue normally, we provide nightly builds of
-the conda packages for the latest developer versions. Unless you want to
-actively develop glue, this is the best way to try out the latest developer
-version. We recommend that you install the developer version into a conda
-environment in case you also want to be able to have the stable version of glue
-in your normal environment (we'll show how to do this in the next few steps).
+If you use conda/mamba, we recommend that you first make a clean environment
+dedicated to developer versions::
 
-To create an environment (which only needs to be done the first time), type::
+    mamba create -n glue-dev-env
+    mamba activate glue-dev-env
 
-    conda create -n glueviz-dev python
+You can then install the latest developer version of glue-core and glue-qt (for the
+Qt desktop application) with::
 
-Then switch to the ``glueviz-dev`` environment::
-
-    source activate glueviz-dev
-
-and install the latest nightly builds of the glue packages with::
-
-    conda install -c glueviz -c glueviz/label/dev glueviz
-
-You should normally see long version numbers for the glue-* packages that get
-installed::
-
-    $ conda install -c glueviz -c glueviz/label/dev glueviz
-    Fetching package metadata .............
-    Solving package specifications: .
-
-    Package plan for installation in environment /Users/tom/miniconda3/envs/glue-dev:
-
-    The following NEW packages will be INSTALLED:
-
-        glue-core:          0.11.0.dev20170705102151.3ea9531-py36_0 glueviz/label/dev
-        glue-vispy-viewers: 0.8.dev20170602171439.7533769-py36_0    glueviz/label/dev
-        glueviz:            0.11.0.dev20170705211525.3af839b-0      glueviz/label/dev
-        pyopengl:           3.1.1a1-np113py36_0
-
-    Proceed ([y]/n)? y
-
-To update to a more recent version of the developer packages, use the same
-command. If you want to switch back to the original environment you were in, you
-can type::
-
-    source activate <environment_name>
-
-where ``<environment_name>>`` might be e.g. ``root`` or ``glueviz-env``
-depending on how you chose to set up your stable glue environment.
-
-From source (if you use conda)
-------------------------------
-
-If you use conda but want to install the latest developer version from the git
-repository (for example if you want to work on the code) then the easiest way to
-get all the dependencies installed is to first install the stable version, which
-will pull in all the dependencies, then to remove it and install the developer
-version::
-
-    conda install -c glueviz glueviz
-    conda remove glueviz
-
-    git clone https://github.com/glue-viz/glue.git
-    cd glue
-    pip install .
-    cd ..
-
-You can also use ``python setup.py develop`` instead of ``pip install .`` if you
-want changes made in the local repository to be reflected immediately in the
-installed version. Note that you can do all this in an environment as described
-in `With conda`_ if you want to have the stable version of glue in a separate
-environment.
-
-The same instructions apply to other glue packages, for example the plugin with
-the 3D viewers::
-
-    conda install -c glueviz glue-vispy-viewers
-    conda remove glue-vispy-viewers
-
-    git clone https://github.com/glue-viz/glue-vispy-viewers.git
-    cd glue-vispy-viewers
-    pip install .
-    cd ..
-
-If you want to uninstall the developer versions and install the stable versions
-again, you can uninstall the developer versions with::
-
-    pip uninstall glueviz glue-vispy-viewers
-
-then install the stable versions with conda as usual.
-
-From source (if you don't use conda)
-------------------------------------
-
-If you don't use conda, but use ``pip`` instead, then you can install the latest
-version of the glue core package using::
-
-    git clone https://github.com/glue-viz/glue.git
-    cd glue
-    pip install -e .
-    cd ..
+    pip install git+https://github.com/glue-viz/glue
+    pip install git+https://github.com/glue-viz/glue-qt

doc/installation/installation.rst

@@ -17,28 +17,16 @@ If your problem is not described there, `open a new issue
    pip
    developer
 
-.. note:: If you are using Apple M1 hardware, be sure to read :ref:`apple-m1`
-          before proceeding with the installation instructions.
-
-Once glue is installed, you will be able to type::
+Once glue is installed, you will either be able do double click on the
+application icon (in the case of the standalone applications) or be able to type::
 
     glue
 
 in a terminal to start glue. Glue accepts a variety of command-line arguments.
-See ``glue --help`` for examples. If you used the Anaconda Navigator, you can
-also launch glue from the navigator, but be aware that errors may be hidden, so
-if you have any issues, try running glue from the command-line.
+See ``glue --help`` for examples.
 
 You can also start glue with the ``-v`` option::
 
     glue -v
 
 to get more verbose output, which may help diagnose issues.
-
-On Windows, installation creates an executable ``glue.exe`` file within the
-python script directory (e.g., ``C:\Python27\Scripts``). Windows users can
-create a desktop shortcut for this file, and run Glue by double clicking on the
-icon.
-
-.. note:: If you have issues with Glue after installing it on MacOS X Big Sur,
-          see :ref:`apple-bigsur`.

doc/known_issues.rst

@@ -17,25 +17,6 @@ checkbox **Open using Rosetta**.
 
 Once you have done this, follow the regular
 :ref:`installation` instructions for glue as if you were using an intel Mac.
-Be sure to also read `Using glue on Big Sur`_ since this is the version of
-MacOS X that is installed on Apple M1 hardware.
-
-.. _apple-bigsur:
-
-Using glue on Big Sur
----------------------
-
-If you have issues with getting the 3D functionality to work, you will need to
-install the latest development version of VisPy. If you are using conda, you
-will first need to remove the conda-installed version of VisPy using::
-
-    conda remove vispy --force
-
-You can then install the latest development version of VisPy with::
-
-    pip install git+https://github.com/vispy/vispy
-
-Once this is done the 3D viewers should work properly.
 
 3D viewers not working on Linux with PyQt5
 ------------------------------------------