Merge pull request #124: Use Intel Miniconda installer for Apple sili…

…con, start an installation FAQ page

src/index.rst

@@ -81,4 +81,5 @@ team and other Nextstrain users provide assistance.  For private inquiries,
     Nextstrain CLI <https://docs.nextstrain.org/projects/cli/en/stable/>
     Nextclade CLI <https://docs.nextstrain.org/projects/nextclade/en/stable/user/nextclade-cli.html>
     Nextalign CLI <https://docs.nextstrain.org/projects/nextclade/en/stable/user/nextalign-cli.html>
+    FAQ <reference/faq>
     reference/style

src/install.rst

@@ -48,9 +48,15 @@ These instructions will install the Nextstrain CLI and tools to run and view you
 
       1. Install Miniconda:
 
-         a. Go to the `installation page <https://docs.conda.io/en/latest/miniconda.html>`_.
-         b. Scroll down to the **Latest Miniconda Installer Links** section and click the MacOSX platform link that ends with **pkg**.
-         c. Open the downloaded file and follow through installation prompts.
+         .. The installer link is taken from https://docs.conda.io/en/latest/miniconda.html.
+
+         a. `Download the installer <https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.pkg>`_.
+
+            .. note::
+
+                  This is the Intel x86 64-bit installer, :ref:`which we recommend even for Mac computers with Apple silicon (e.g. M1) <why-intel-miniconda-installer-on-apple-silicon>`.
+
+         b. Open the downloaded file and follow through installation prompts.
 
       2. Open a terminal window.
       3. Install Mamba on the ``base`` Conda environment:
@@ -83,21 +89,6 @@ These instructions will install the Nextstrain CLI and tools to run and view you
 
             .. group-tab:: Native
 
-               .. warning::
-
-                  If using a newer Mac with an `Apple silicon chip <https://support.apple.com/en-us/HT211814>`_ (e.g. M1), first run these commands to ensure Conda creates the environment with ``osx-64`` emulation:
-
-                  .. code-block:: bash
-
-                     # Create a new environment using Intel packages called base_osx-64
-                     CONDA_SUBDIR=osx-64 conda create -n base_osx-64 python
-
-                     # Activate new Intel-based environment
-                     conda activate base_osx-64
-
-                     # Ensure future Conda commands in this environment use Intel packages too.
-                     conda config --env --set subdir osx-64
-
                1. Create a Conda environment named ``nextstrain``:
 
                   .. include:: snippets/conda-create-bash.rst

src/reference/faq.rst

@@ -0,0 +1,29 @@
+================================
+Frequently Asked Questions (FAQ)
+================================
+
+.. TODO: Add a table of contents once there are more sections. Doesn't seem necessary at the time of writing.
+
+Installation
+============
+
+There are many ways to install Nextstrain, and we aim to simplify the installation guide so it is easy to follow along. Here, you will find answers to some common questions about the installation process.
+
+.. _why-intel-miniconda-installer-on-apple-silicon:
+
+Why recommend the Intel Miniconda installer for Mac computers with Apple silicon (e.g. M1)?
+-------------------------------------------------------------------------------------------
+
+.. note::
+
+   `How to tell if your Mac has an Apple silicon chip <https://support.apple.com/en-us/HT211814>`_
+
+Apple silicon chips are great and efficient. However, many existing packages have not yet added support to run on these chips natively. An easy way to identify support on the `Bioconda packages page <https://anaconda.org/bioconda>`_ is to look for ``noarch`` or ``osx-arm64`` under the **Installers** section of a package. Without any of those, a package is not able to be installed natively on Apple silicon. This is the case for packages such as `MAFFT <https://anaconda.org/bioconda/mafft>`_ (a dependency of :term:`Augur`) and many other bioinformatics packages. For this reason, using an Apple silicon Miniconda installation for the average bioinformatics researcher can result in a difficult experience. To circumvent this, one may enable ``osx-64`` emulation using the ``subdir`` config on each Conda environment, but it is easier to install with emulation by default.
+
+For those who really want to use the ``arm64`` Miniconda installer, it is still possible to set up the ``nextstrain`` Conda environment by configuring it to run with emulation. Run this after setting up the empty Conda environment and before the ``mamba install`` command:
+
+.. code-block:: bash
+
+   conda config --env --set subdir osx-64
+
+This will ensure that all commands in the active Conda environment are run using ``osx-64`` emulation, making it possible to install all the software required for Nextstrain to run.