Merge pull request #628 from molpopgen/more_conda_docs

Add more detailed docs on conda envs.

doc/pages/userenv.rst

@@ -68,6 +68,49 @@ The basic steps are:
         - defaults
 
 
+Working in "environments"
+++++++++++++++++++++++++++++++++++++++++
+
+.. note::
+
+   The stability of conda installation into environments is a moving target.
+   We will try to keep this up to date.
+
+Many users prefer to set up different environments for different projects.
+Doing so requires some care.
+Currently, `conda-forge`, the channel from which `bioconda` pulls dependencies, builds for Python versions not supported by `bioconda`.
+Thus, building an environment like this will often lead to failure:
+
+.. code-block:: bash
+
+   conda create -n myenv -y
+
+The problem here is that installing dependencies that are *not* from `bioconda` is likely to pull in Python 3.9, leaving you unable to install `bioconda` packages.
+(Currently, `bioconda` only supports up to Python 3.8.)
+
+Unfortunately, creating a new environment based on Python 3.8 will also lead to failure:
+
+.. code-block:: bash
+
+   conda create -n myenv python=3.8 -y
+
+The problem here is that the Python 3.8 build will be upgraded compared to what came with `miniconda`.
+For reasons that we are unable to understand, this upgrade leads to run-time problems in some instances.
+
+Thus, the safest thing to do is to clone your `base`:
+
+.. code-block:: bash
+
+   conda create -n myenv --clone base
+
+Now, `myenv` is an exact copy of `base`, and you can `conda install fwdpy11` successfully.
+This solution is safest if you never install anything into `base`, leaving it as it was when you installed `miniconda`.
+
+.. warning::
+
+   When working in environments, never `conda update`!
+   Updating is likely to do *bad things* to dependencies that you won't notice until you run something.
+
 Conda compilers
 ++++++++++++++++++++++++++++++++++++++++