backport new environment file and install instructions (#7979)

drammock · web-flow · commit 76fc838e954e · 2020-07-10T14:52:56.000-04:00
* only update install instructions

* add nitpick ignore

* another nitpick
diff --git a/doc/conf.py b/doc/conf.py
@@ -110,6 +110,16 @@
                                                               td.isoformat())
 
 nitpicky = True
+nitpick_ignore = [
+    ("py:class", "None.  Remove all items from D."),
+    ("py:class", "a set-like object providing a view on D's items"),
+    ("py:class", "a set-like object providing a view on D's keys"),
+    ("py:class", "v, remove specified key and return the corresponding value."),  # noqa: E501
+    ("py:class", "None.  Update D from dict/iterable E and F."),
+    ("py:class", "an object providing a view on D's values"),
+    ("py:class", "a shallow copy of D"),
+    ("py:class", "(k, v), remove and return some (key, value) pair as a"),
+]
 suppress_warnings = ['image.nonlocal_uri']  # we intentionally link outside
 
 # The version info for the project you're documenting, acts as replacement for
diff --git a/doc/install/advanced.rst b/doc/install/advanced.rst
@@ -57,6 +57,13 @@ interactivity within the scene is limited in non-blocking plot calls.
      In [1]: from mayavi import mlab
      In [2]: %gui qt
 
+If you installed the ``nb_conda_kernels`` package into your ``base``
+environment (as recommended), you should be able to launch ``mne``-capable
+notebooks from within the Anaconda Navigator GUI without having to explicitly
+switch to the ``mne`` environment first; look for ``Python [conda env:mne]``
+when choosing which notebook kernel to use. Otherwise, be sure to activate the
+``mne`` environment before launching the notebook.
+
 If you use another Python setup and you encounter some difficulties please
 report them on the `MNE mailing list`_ or on the `GitHub issues page`_ to get
 assistance.
diff --git a/doc/install/mne_python.rst b/doc/install/mne_python.rst
@@ -36,7 +36,7 @@ To get started, follow the `installation instructions for Anaconda`_.
    (indeed, preferable) to leave ``PYTHONPATH`` and ``PYTHONHOME`` permanently
    unset.
 
-When you are done, if you type the following commands in a ``bash`` terminal,
+When you are done, if you type the following commands in a command shell,
 you should see outputs similar to the following (assuming you installed
 conda to ``/home/user/anaconda3``)::
 
@@ -54,14 +54,16 @@ conda to ``/home/user/anaconda3``)::
     .. rubric:: If you are on a |windows| Windows command prompt:
 
     Most of our instructions start with ``$``, which indicates
-    that the commands are designed to be run from a Bash command prompt.
+    that the commands are designed to be run from a ``bash`` command shell.
 
-    Windows command prompts do not expose the same command-line tools as Bash
-    shells, so things like ``which`` will not work, and you need to use
-    alternatives, such as::
+    Windows command prompts do not expose the same command-line tools as
+    ``bash`` shells, so commands like ``which`` will not work. You can test
+    your installation in Windows ``cmd.exe`` shells with ``where`` instead::
 
-        > where mne
-        C:\Users\mneuser\Anaconda3\Scripts\mne
+        > where python
+        C:\Users\user\anaconda3\python.exe
+        > where pip
+        C:\Users\user\anaconda3\Scripts\pip.exe
 
     .. rubric:: If you see something like:
 
@@ -79,13 +81,18 @@ conda to ``/home/user/anaconda3``)::
     (probably at or near the beginning), but the ``command not found`` error
     suggests that it is missing.
 
-    On Linux or OSX, the installer should have put something
-    like the following in your ``~/.bashrc`` or ``~/.bash_profile``
-    (or somewhere else if you are using a non-bash terminal):
+    On Linux or macOS, the installer should have put something
+    like the following in your ``~/.bashrc`` or ``~/.bash_profile`` (or your
+    ``.zprofile`` if you're using macOS Catalina or later, where the default
+    shell is ``zsh``):
 
     .. code-block:: bash
 
-        . ~/anaconda3/etc/profile.d/conda.sh
+        # >>> conda initialize >>>
+        # !! Contents within this block are managed by 'conda init' !!
+        __conda_setup= ...
+        ...
+        # <<< conda initialize <<<
 
     If this is missing, it is possible that you are not on the same shell that
     was used during the installation. You can verify which shell you are on by
@@ -94,22 +101,14 @@ conda to ``/home/user/anaconda3``)::
         $ echo $SHELL
 
     If you do not find this line in the configuration file for the shell you
-    are using (bash, tcsh, etc.), add the line to that shell's ``rc`` or
-    ``profile`` file to fix the problem.
+    are using (bash, zsh, tcsh, etc.), try running::
 
-    .. rubric:: If you see an error like:
-
-    ::
-
-        CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'.
-
-    It means that you have used an old method to set up Anaconda. This
-    means that you have something like::
+        conda init
 
-        PATH=~/anaconda3/bin:$PATH
-
-    in your ``~/.bash_profile``. You should update this line to use
-    the modern way using ``anaconda3/etc/profile.d/conda.sh`` above.
+    in your command shell. If your shell is not ``cmd.exe`` (Windows) or
+    ``bash`` (Linux, macOS) you will need to pass the name of the shell to the
+    ``conda init`` command. See ``conda init --help`` for more info and
+    supported shells.
 
     You can also consult the Anaconda documentation and search for
     Anaconda install tips (`Stack Overflow`_ results are often helpful)
@@ -120,29 +119,61 @@ conda to ``/home/user/anaconda3``)::
 Installing MNE-Python and its dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Once you have Anaconda installed, the easiest way to install
-MNE-Python with all dependencies is update your base Anaconda environment:
+Once you have Python/Anaconda installed, you have a few choices for how to
+install MNE-Python.
 
-.. _environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
+For sensor-level analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you only need 2D plotting capabilities with MNE-Python (i.e., most EEG/ERP
+or other sensor-level analyses), you can install all you need by running
+``pip install mne`` in a terminal window (on Windows, use the "Anaconda Prompt"
+from the Start menu, or the "CMD.exe prompt" from within the Anaconda Navigator
+GUI). This will install MNE-Python into the "base" conda environment, which
+should be active by default and should already have the necessary dependencies
+(``numpy``, ``scipy``, and ``matplotlib``).
+
+For 3D plotting and source analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need MNE-Python's 3D plotting capabilities (e.g., plotting estimated
+source activity on a cortical surface) it is a good idea to install
+MNE-Python into its own virtual environment, so that the extra dependencies
+needed for 3D plotting stay in sync (i.e., they only get updated to versions
+that are compatible with MNE-Python). See the detailed instructions below for
+your operating system.
 
 .. collapse:: |linux| Linux
 
-   Use the base `environment file`_, e.g.::
+   Download the MNE-Python `environment file`_ (done here with ``curl``) and
+   use it to create a new environment (named ``mne`` by default)::
 
        $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
        $ conda env update --file environment.yml
 
+   .. collapse:: |hand-stop-o| If you get errors building mayavi...
+       :class: danger
+
+       Installing `mayavi`_ needs OpenGL support. On debian-like systems this
+       means installing ``libopengl0``, i.e., ``sudo apt install libopengl0``.
+
 .. collapse:: |apple| macOS
 
-   Use the base `environment file`_, e.g.::
+   Update the ``base`` conda environment to include the ``nb_conda_kernels``
+   package, so you can use MNE-Python in Jupyter Notebooks launched from the
+   Anaconda GUI. Then download the MNE-Python `environment file`_ (done here
+   with ``curl``) and use it to create a new environment (named ``mne`` by
+   default)::
 
+       $ conda install --name base nb_conda_kernels
        $ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
        $ conda env update --file environment.yml
 
 .. collapse:: |windows| Windows
 
-   - Download the base `environment file`_
+   - Download the `environment file`_
    - Open an Anaconda command prompt
+   - Run :samp:`conda install --name base nb_conda_kernels`
    - :samp:`cd` to the directory where you downloaded the file
    - Run :samp:`conda env update --file environment.yml`
 
@@ -170,9 +201,17 @@ you can create a new dedicated environment (here called "mne") with
     });
     </script>
 
-.. collapse:: |hand-stop-o| If you are installing on a headless server...
+Installing to a headless server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. collapse:: |server| If you are installing on a headless server...
     :class: danger
 
+    With `pyvista`_:
+    Follow the steps described in :ref:`standard_instructions`
+    but use the `server environment file`_ instead of the `environment file`_.
+
+    With `mayavi`_:
     Installing `mayavi`_ requires a running `X server`_. If you are
     installing MNE-Python into a computer with no display connected to it, you
     can try removing `mayavi`_ from the :file:`environment.yml` file before
@@ -191,31 +230,33 @@ Testing MNE-Python installation
 To make sure MNE-Python installed itself and its dependencies correctly,
 type the following command in a terminal::
 
-    $ mne sys_info
+    $ python -c "import mne; mne.sys_info()"
 
 This should display some system information along with the versions of
 MNE-Python and its dependencies. Typical output looks like this::
 
-    Platform:      Linux-4.18.0-13-generic-x86_64-with-debian-buster-sid
-    Python:        3.6.8 |Anaconda, Inc.| (default, Dec 30 2018, 01:22:34)  [GCC 7.3.0]
-    Executable:    /home/travis/miniconda/bin/python
-    CPU:           x86_64: 48 cores
-    Memory:        62.7 GB
+    Platform:      Linux-5.0.0-1031-gcp-x86_64-with-glibc2.2.5
+    Python:        3.8.1 (default, Dec 20 2019, 10:06:11)  [GCC 7.4.0]
+    Executable:    /home/travis/virtualenv/python3.8.1/bin/python
+    CPU:           x86_64: 2 cores
+    Memory:        7.8 GB
 
-    mne:           0.17.0
-    numpy:         1.15.4 {blas=mkl_rt, lapack=mkl_rt}
-    scipy:         1.2.0
-    matplotlib:    3.0.2 {backend=Qt5Agg}
+    mne:           0.21.dev0
+    numpy:         1.19.0.dev0+8dfaa4a {blas=openblas, lapack=openblas}
+    scipy:         1.5.0.dev0+f614064
+    matplotlib:    3.2.1 {backend=Qt5Agg}
 
-    sklearn:       0.20.2
-    numba:         0.45.0
-    nibabel:       2.3.3
+    sklearn:       0.22.2.post1
+    numba:         0.49.0
+    nibabel:       3.1.0
     cupy:          Not found
-    pandas:        0.24.0
-    dipy:          0.15.0
-    mayavi:        4.7.1 {qt_api=pyqt5, PyQt5=5.10.1}
-    pyvista:       0.21.3
-    vtk:           8.2.0
+    pandas:        1.0.3
+    dipy:          1.1.1
+    mayavi:        4.7.2.dev0
+    pyvista:       0.25.2 {pyvistaqt=0.1.0}
+    vtk:           9.0.0
+    PyQt5:         5.14.1
+
 
 .. collapse:: |hand-stop-o| If you get an error...
     :class: danger
@@ -228,26 +269,88 @@ MNE-Python and its dependencies. Typical output looks like this::
           File "<string>", line 1, in <module>
         ModuleNotFoundError: No module named 'mne'
 
-    This suggests that your environment containing ``mne`` is not active.
-    If you installed to the ``mne`` instead of ``base`` environment, try doing
-    ``conda activate mne`` and try again. If this works, you might want to
-    add ``conda activate mne`` to the end of your ``~/.bashrc`` or
-    ``~/.bash_profile`` files so that it gets executed automatically.
+    This suggests that your environment containing MNE-Python is not active.
+    If you followed the setup for 3D plotting/source analysis (i.e., you
+    installed to a new ``mne`` environment instead of the ``base`` environment)
+    try running ``conda activate mne`` first, and try again. If this works,
+    you might want to set your terminal to automatically activate the
+    ``mne`` environment each time you open a terminal::
+
+        $ echo conda activate mne >> ~/.bashrc    # for bash shells
+        $ echo conda activate mne >> ~/.zprofile  # for zsh shells
 
 If something else went wrong during installation and you can't figure it out,
 check out the :doc:`advanced` page to see if your problem is discussed there.
 If not, the `MNE mailing list`_ and `MNE gitter channel`_ are
 good resources for troubleshooting installation problems.
 
+
+Installing a Python IDE
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most users find it convenient to write and run their code in an `Integrated
+Development Environment`_ (IDE). Some popular choices for scientific
+Python development are:
+
+- `Spyder`_ is a free and open-source IDE developed by and for scientists who
+  use Python. It is included by default in the ``base`` environment when you
+  install Anaconda, and can be started from a terminal with the command
+  ``spyder`` (or on Windows or macOS, launched from the Anaconda Navigator GUI).
+  If you installed MNE-Python into a separate ``mne`` environment (not the
+  ``base`` Anaconda environment), you can set up Spyder to use the ``mne``
+  environment automatically, by opening Spyder and navigating to
+  :samp:`Tools > Preferences > Python Interpreter > Use the following interpreter`.
+  There, paste the output of the following terminal command::
+
+      $ conda activate mne && python -c "import sys; print(sys.executable)"
+
+  It should be something like ``C:\Users\user\anaconda3\envs\mne\python.exe``
+  (Windows) or ``/Users/user/anaconda3/envs/mne/bin/python`` (macOS).
+- `Visual Studio Code`_ (often shortened to "VS Code" or "vscode") is a
+  development-focused text editor that supports many programming languages in
+  addition to Python, includes an integrated terminal console, and has a rich
+  ecosystem of packages to extend its capabilities. Installing
+  `Microsoft's Python Extension
+  <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`__ is
+  enough to get most Python users up and running. VS Code is free and
+  open-source.
+- `Atom`_ is a text editor similar to vscode, with a package ecosystem that
+  includes a `Python IDE package <https://atom.io/packages/ide-python>`__ as
+  well as `several <https://atom.io/packages/atom-terminal>`__
+  `packages <https://atom.io/packages/atom-terminal-panel>`__
+  `for <https://atom.io/packages/terminal-plus>`__
+  `integrated <https://atom.io/packages/platformio-ide-terminal>`__
+  `terminals <https://atom.io/packages/term3>`__. Atom is free and open-source.
+- `SublimeText`_ is a general-purpose text editor that is fast and lightweight,
+  and also has a rich package ecosystem. There is a package called `Terminus`_
+  that provides an integrated terminal console, and a (confusingly named)
+  package called "anaconda"
+  (`found here <https://packagecontrol.io/packages/Anaconda>`__) that provides
+  many Python-specific features. SublimeText is free (closed-source shareware).
+- `PyCharm`_ is an IDE specifically for Python development that provides an
+  all-in-one installation (no extension packages needed). PyCharm comes in a
+  free "community" edition and a paid "professional" edition, and is
+  closed-source.
+
 .. highlight:: python
 
 **Next:** :doc:`freesurfer`
 
 
 .. LINKS
 
+.. _environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
+.. _server environment file: https://raw.githubusercontent.com/mne-tools/mne-python/master/server_environment.yml
 .. _`mayavi`: https://docs.enthought.com/mayavi/mayavi/
+.. _`pyvista`: https://docs.pyvista.org/
 .. _`X server`: https://en.wikipedia.org/wiki/X_Window_System
 .. _`xvfb`: https://en.wikipedia.org/wiki/Xvfb
 .. _`off-screen rendering`: https://docs.enthought.com/mayavi/mayavi/tips.html#off-screen-rendering
 .. _`rendering with a virtual framebuffer`: https://docs.enthought.com/mayavi/mayavi/tips.html#rendering-using-the-virtual-framebuffer
+.. _`integrated development environment`: https://en.wikipedia.org/wiki/Integrated_development_environment
+.. _`spyder`: https://www.spyder-ide.org/
+.. _`visual studio code`: https://code.visualstudio.com/
+.. _`sublimetext`: https://www.sublimetext.com/
+.. _`terminus`: https://packagecontrol.io/packages/Terminus
+.. _`pycharm`: https://www.jetbrains.com/pycharm/
+.. _`atom`: https://atom.io/
diff --git a/doc/install/pre_install.rst b/doc/install/pre_install.rst
@@ -18,7 +18,7 @@ Overview of the MNE tools suite
 
 - :doc:`MNE-Python <../python_reference>` reimplements the functionality of
   MNE-C, and extends considerably the analysis and visualization capabilities.
-  MNE-Python is collaboratively developed and has more than 150 contributors.
+  MNE-Python is collaboratively developed and has more than 200 contributors.
 
 - The :ref:`mne_matlab` provides a MATLAB interface to the .fif file
   format and other MNE data structures, and provides example MATLAB
