[MRG+1] Add notes for Python 3 transition (mne-tools#5256)

* Add notes for Python 3 transition

* Streamline text

* Format as note in README.rst

* Revert "Format as note in README.rst"

This reverts commit 4284ae0.

* Typo and FA icons

* Bold note

* Link Stack Overflow

* Test to see if code blocks can be nested within note blocks...

* Nest code in note blocks

* Try fontawesome sphinx plugin

* Custom admonitions

* STY: Fix text color

* Try something else instead of admonitions

* Try if adding an existing CSS class works (probably not)

* Revert CSS color change (inherit works fine now)

README.rst

@@ -61,6 +61,8 @@ To install the latest stable version of MNE-Python, you can use `pip <https://pi
 
     pip install -U mne
 
+**Note** that MNE-Python 0.17 will be the last release to support Python 2. From MNE-Python 0.18, only Python 3 will be supported.
+
 For more complete instructions and more advanced installation methods (e.g. for
 the latest development version), see the `getting started page`_.
 

doc/conf.py

@@ -20,6 +20,7 @@
 import sphinx_gallery  # noqa
 import sphinx_bootstrap_theme
 from numpydoc import numpydoc, docscrape  # noqa
+import sphinx_fontawesome
 import mne
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -53,6 +54,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.todo',
     'sphinx_gallery.gen_gallery',
+    'sphinx_fontawesome',
     'numpydoc',
     'gen_commands',
 ]

doc/install_mne_python.rst

@@ -5,87 +5,74 @@
 Installing MNE-Python
 ---------------------
 
-There are many possible ways to install a Python interpreter and MNE.
-Here we provide guidance for the simplest, most well tested solution.
+There are many ways to install a Python interpreter and MNE. Here we show a simple well tested solution.
 
-1. Get a Python interpreter
-###########################
+1. Get Python
+#############
 
-* We recommend the Anaconda Python 3+ distribution.
-  Follow `their installation instructions <http://docs.continuum.io/anaconda/install>`_.
-  When you are done, you should see some variant of this in a terminal:
+We recommend the `Anaconda distribution <https://www.anaconda.com/distribution/>`_.
+Follow the `installation instructions <http://docs.continuum.io/anaconda/install>`_.
+When you are done, you should see a similar output if you type the following command in a terminal:
 
-  .. code-block:: console
+.. code-block:: console
+
+    $ conda --version && python --version
+    conda 4.5.4
+    Python 3.6.5 :: Anaconda, Inc.
 
-      $ conda --version && python --version
-      conda 4.4.10
-      Python 3.6.4 :: Continuum Analytics, Inc.
+If you get an error message, consult the Anaconda documentation and search for Anaconda install
+tips (`Stack Overflow <https://stackoverflow.com/>`_ results are often helpful).
 
-  If it doesn't, something went wrong.
-  Look through the Anaconda documentation and Google Anaconda install
-  tips (StackExchange results are often helpful).
+.. note:: MNE-Python 0.17 will be the last release to support Python 2. From MNE-Python 0.18, only Python 3 will be supported.
 
 2. Get MNE and its dependencies
 ###############################
 
-* From the command line, install the MNE dependencies to a dedicated ``mne`` Anaconda environment.
-
-  .. code-block:: console
+From the command line, install the MNE dependencies to a dedicated ``mne`` Anaconda environment.
 
-      $ curl -O https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
-      $ conda env create -f environment.yml
-      $ source activate mne
+.. code-block:: console
 
-  Use any web browser to download ``environment.yml`` if you do not have ``curl``
+    $ curl -O https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
+    $ conda env create -f environment.yml
+    $ conda activate mne
 
-.. raw:: html
+You can also use a web browser to `download the required environment file <https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml>`_ if you do not have ``curl``.
 
-  <ul><li><p class="first"><b><i class="fa fa-apple"></i> macOS users only</b></p>
+.. admonition:: |apple| macOS
+  :class: note
 
-Manually update PyQt5. This step is not needed on Linux, and breaks things on Windows.
+  If you are on macOS, you need to manually update PyQt5. This step is not needed on Linux, and even breaks things on Windows.
 
-.. code-block:: console
+  .. code-block:: console
 
     $ pip install --upgrade pyqt5>=5.10
 
-.. raw:: html
-
-  </li></ul>
-
 
 3. Check that everything works
 ##############################
 
-* To check that everything worked, do:
-
-  .. code-block:: console
-
-      $ python
-
-  This should open an Anaconda Python prompt, where you can now do::
-
-      >>> import mne
-
-  If you get a new prompt with no error messages, you should be good to go!
+To make sure everything installed correctly, type the following command in a terminal:
 
+.. code-block:: console
 
-.. raw:: html
+    $ python
 
-  <ul><li><p class="first"><b><i class="fa fa-windows"></i> Windows users only</b></p>
+This should open an interactive Python prompt, where you can type:
 
-In IPython, using the magic ``%gui qt`` after importing MNE, Mayavi, or PySurfer might be
-`necessary <https://github.com/ipython/ipython/issues/10384>`_, e.g.:
+    >>> import mne
 
-.. code-block:: ipython
+If you get a new prompt with no error messages, you should be good to go!
 
-   In [1]: from mayavi import mlab
-   In [2]: %gui qt
+.. admonition:: |windows| Windows
+  :class: note
 
-.. raw:: html
+  If you are on Windows, you might have to use the IPython magic command ``%gui qt``
+  after importing MNE, Mayavi or PySurfer (see `here <https://github.com/ipython/ipython/issues/10384>`_):
 
-  </li></ul>
+  .. code-block:: ipython
 
+     In [1]: from mayavi import mlab
+     In [2]: %gui qt
 
-* For advanced topics like how to get :ref:`CUDA` support or if you're
-  having trouble, visit :ref:`advanced_setup`.
+For advanced topics like how to get :ref:`CUDA` support or if you are experiencing other issues, check out :ref:`advanced_setup`.
 

doc/whats_new.rst

@@ -49,6 +49,7 @@ Bug
 API
 ~~~
 
+- Prepare transition to Python 3. This release will be the last release compatible with Python 2. The next version will be Python 3 only.
 
 .. _changes_0_16:
 

environment.yml

@@ -43,3 +43,4 @@ dependencies:
   - sphinx_bootstrap_theme
   - "https://api.github.com/repos/sphinx-gallery/sphinx-gallery/zipball/master"
   - python-picard
+  - sphinx_fontawesome

environment2.yml

@@ -42,3 +42,4 @@ dependencies:
   - sphinx_bootstrap_theme
   - git+https://github.com/sphinx-gallery/sphinx-gallery.git
   - python-picard
+  - sphinx_fontawesome